Use las API del Traductor de Azure AI

  • Artículo

En esta guía paso a paso, aprenderá a usar las API REST del servicio Translator. Empiece con ejemplos básicos y pase a algunas de las opciones de configuración principales que se suelen usar durante el desarrollo, entre las que se incluyen:

Requisitos previos

  • Una suscripción a Azure: cree una cuenta gratuita

  • Un recurso multiservicio o Traductor de Azure AI. Una vez que tenga la suscripción de Azure, cree un recurso de servicio único o de varios servicios en Azure Portal para obtener la clave y el punto de conexión. Tras su implementación, seleccione Ir al recurso.

  • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.

  • Tanto la clave como el punto de conexión del recurso son necesarios para conectar la aplicación al servicio Translator. Posteriormente, pegará la clave y el punto de conexión en los códigos de ejemplo. Puede encontrar estos valores en la página Claves y punto de conexión de Azure Portal:

    Captura de pantalla: página Claves y punto de conexión de Azure Portal.

Importante

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como Azure Key Vault. Para más información, consulte el artículo sobre seguridad de los servicios de Azure AI.

Encabezados

Para llamar al servicio Translator a través de la API de REST, tendrá que asegurarse de que incluye los siguientes encabezados en todas las solicitudes. No se preocupe, en las siguientes secciones incluiremos los encabezados en el código de ejemplo.

Encabezado Valor Condición
Ocp-Apim-Subscription-Key En este encabezado se incluye la clave de servicio de Translator de Azure Portal.
  • Se requiere
Ocp-Apim-Subscription-Region La región donde se creó el recurso.
  • Se requiere cuando se usa un recurso de Azure AI multiservicio o regional (geográfico), como Oeste de EE. UU.
  • Opcional cuando se usa un recurso de Translator de servicio único.
Content-Type En este encabezado se especifica el tipo de contenido de la carga. Los valores que se aceptan son application/json o charset=UTF-8.
  • Requerido
Content-Length Este encabezado especifica la longitud del cuerpo de la solicitud.
  • Opcional
X-ClientTraceId GUID generado por el cliente para identificar de forma única la solicitud. Puede omitir este encabezado si incluye el id. de seguimiento en la cadena de la consulta mediante un parámetro de consulta denominado ClientTraceId.
  • Opcional

Configuración de la aplicación

  1. Asegúrese de que tiene instalada la versión actual del IDE de Visual Studio.

    Sugerencia

    Si es la primera vez que usa Visual Studio, pruebe el módulo de Learn Introducción a Visual Studio.

  2. Abra Visual Studio.

  3. En la página Inicio, seleccione Crear un nuevo proyecto.

    Captura de pantalla: ventana de inicio de Visual Studio.

  4. En la página Crear un proyecto, escriba consola en el cuadro de búsqueda. Elija la plantilla Aplicación de consola y, a continuación, seleccione Siguiente.

    Captura de pantalla: página Crear un proyecto de Visual Studio.

  5. En la ventana de diálogo Configure su nuevo proyecto, escriba translator_text_app en el cuadro Nombre de proyecto. Deje desactivada la casilla "Colocar la solución y el proyecto en el mismo directorio" y seleccione el botón Siguiente.

    Captura de pantalla: ventana de diálogo Configure su nuevo proyecto de Visual Studio.

  6. En la ventana de diálogo Información adicional, asegúrese de que esté seleccionado el elemento .NET 6.0 (compatibilidad a largo plazo). Deje la casilla "No usar instrucciones de nivel superior" desactivada y seleccione Crear.

    Captura de pantalla: ventana de diálogo de información adicional de Visual Studio.

Instalación del paquete Newtonsoft.json con NuGet

  1. Haga clic con el botón derecho sobre el proyecto formRecognizer_quickstart y seleccione Administrar paquetes NuGet...

    Captura de pantalla del cuadro de búsqueda de paquetes NuGet.

  2. Seleccione la pestaña Examinar y escriba Newtonsoft.

    Captura de pantalla de la ventana de instalación de paquetes NuGet.

  3. Seleccione "Instalar" en la ventana derecha del administrador de paquetes para agregar el paquete al proyecto.

    Captura de pantalla del botón de instalación de paquetes NuGet.

Compilación de la aplicación

Nota

  • A partir de .NET 6, los nuevos proyectos que usan la plantilla console generan un nuevo estilo de programa que difiere de las versiones anteriores.
  • El nuevo tipo de salida usa características recientes de C# que simplifican el código que debe escribir.
  • Cuando se usa la versión más reciente, solo es necesario escribir el cuerpo del método Main. Es decir, no es necesario incluir instrucciones de nivel superior, directivas Using globales o directivas Using implícitas.
  • Para obtener más información, consulteLas nuevas plantillas de C# generan instrucciones de nivel superior.

  1. Abra el archivo Program.cs.

  2. Elimine el código preexistente, incluida la línea Console.WriteLine("Hello World!"). Copie y pegue los códigos de ejemplo en el archivo Program.cs de la aplicación. Por cada código de ejemplo, asegúrese de actualizar las variables de clave y punto de conexión con valores de la instancia de Translator en Azure Portal.

  3. Una vez agregado un código de ejemplo deseado a la aplicación, elija el botón verde Iniciar junto a formRecognizer_quickstart para compilar y ejecutar el programa, o presione F5.

Captura de pantalla del botón Ejecutar programa en Visual Studio

Importante

Los ejemplos de esta guía requieren claves y puntos de conexión codificados de forma rígida. Recuerde quitar la clave del código cuando haya terminado y nunca la haga pública. En el caso de producción, considere la posibilidad de usar alguna forma segura de almacenar las credenciales, y acceder a ellas. Para más información, consulteSeguridad de los servicios de Azure AI.

Traducir texto

La operación básica del servicio Translator es traducir texto. En esta sección, creará una solicitud que toma un solo origen (from) y genera dos salidas (to). Luego, conocerá algunos parámetros que se pueden usar para ajustar tanto la solicitud como la respuesta.

using System.Text;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&from=en&to=sw&to=it";
        string textToTranslate = "Hello, friend! What did you do today?";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
   {
      "translations":[
         {
            "text":"Halo, rafiki! Ulifanya nini leo?",
            "to":"sw"
         },
         {
            "text":"Ciao, amico! Cosa hai fatto oggi?",
            "to":"it"
         }
      ]
   }
]

Puede comprobar el consumo (el número de caracteres que se le cobrará) de cada solicitud del campo encabezados de respuesta: x-metered-usage.

Detectar idioma

Si necesita una traducción, pero no sabe el idioma del texto, puede usar la operación de detección de idioma. Hay más de una manera de identificar el idioma del texto de origen. En esta sección, aprenderá a usar la detección de idiomas mediante el punto de conexión translate y el punto de conexión detect.

Detección del idioma de origen durante la traducción

Si no incluye el parámetro from en la solicitud de traducción, el servicio Translator intentará detectar el idioma del texto de origen. En la respuesta, encontrará el idioma detectado (language) y una puntuación de confianza (score). Cuando más se aproxime score a 1.0, mayor será la confianza en que la detección sea correcta.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
// required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Output languages are defined as parameters, input language detected.
        string route = "/translate?api-version=3.0&to=en&to=it";
        string textToTranslate = "Halo, rafiki! Ulifanya nini leo?";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            // location required if you're using a multi-service or regional (not global) resource. 
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
   {
      "detectedLanguage":{
         "language":"sw",
         "score":0.8
      },
      "translations":[
         {
            "text":"Hello friend! What did you do today?",
            "to":"en"
         },
         {
            "text":"Ciao amico! Cosa hai fatto oggi?",
            "to":"it"
         }
      ]
   }
]

Detección del idioma de origen sin traducción

El servicio Translator se puede usar exclusivamente para detectar el idioma del texto de origen, no para traducirlo. Para ello, use el punto de conexión /detect.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
// required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Just detect language
        string route = "/detect?api-version=3.0";
        string textToLangDetect = "Hallo Freund! Was hast du heute gemacht?";
        object[] body = new object[] { new { Text = textToLangDetect } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

La respuesta del punto de conexión /detect incluye detecciones alternativas e indica si se admiten la traducción y la transliteración en todos los idiomas detectados. Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
   {
      "language":"de",

      "score":1.0,

      "isTranslationSupported":true,

      "isTransliterationSupported":false
   }
]

Transliteración de texto

La transliteración es el proceso de convertir una palabra o una frase del guión (alfabeto) de un idioma al de otro en función de su similitud fonética. Por ejemplo, la transliteración se puede usar para convertir "สวัสดี" (thai) en "sawatdi" (latn). Hay más de una forma de realizar la transliteración. En esta sección, aprenderá a usar la detección de idiomas mediante el punto de conexión translate y el punto de conexión transliterate.

Transliteración durante la traducción

Si va a realizar una traducción a un idioma que usa un alfabeto (o fonemas) distinto que el del texto de origen, es probable que lo que necesita sea una transliteración. En este ejemplo, se va a traducir "Hello" de inglés a tailandés. Además de obtener la traducción en tailandés, obtendrá una transliteración de la frase traducida en la que se usa el alfabeto latino.

Para obtener una transliteración desde el punto de conexión translate, use el parámetro toScript.

Nota

Para obtener una lista completa de las opciones de transliteración y los idiomas disponibles, consulte el artículo sobre los idiomas admitidos.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Output language defined as parameter, with toScript set to latn
        string route = "/translate?api-version=3.0&to=th&toScript=latn";
        string textToTransliterate = "Hello, friend! What did you do today?";
        object[] body = new object[] { new { Text = textToTransliterate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta. Tenga en cuenta que la respuesta del punto de conexión translate incluye el idioma de origen detectado con una puntuación de confianza, una traducción en la que se usa el alfabeto del idioma de la salida y una transliteración en la que se usa el alfabeto latino.

[
  {
    "detectedLanguage": {
      "language": "en",
      "score": 1
    },
    "translations": [
      {
        "text": "หวัดดีเพื่อน! วันนี้เธอทำอะไรไปบ้าง ",
        "to": "th",
        "transliteration": {
          "script": "Latn",
          "text": "watdiphuean! wannithoethamaraipaiang"
        }
      }
    ]
  }
]

Transliteración sin traducción

Para que se realice una transliteración también puede usar el punto de conexión transliterate. Si se usa el punto de conexión de transliteración, es preciso especificar el idioma de origen (language), el guión o alfabeto de destino (fromScript), y el guión o alfabeto de la salida (toScript) como parámetros. En este ejemplo, se va a hacer la transliteración de สวัสดีเพื่อน. วันนี้คุณทำอะไร.

Nota

Para obtener una lista completa de las opciones de transliteración y los idiomas disponibles, consulte el artículo sobre los idiomas admitidos.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // For a complete list of options, see API reference.
        // Input and output languages are defined as parameters.
        string route = "/transliterate?api-version=3.0&language=th&fromScript=thai&toScript=latn";
        string textToTransliterate = "สวัสดีเพื่อน! วันนี้คุณทำอะไร";
        object[] body = new object[] { new { Text = textToTransliterate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta. A diferencia de la llamada al punto de conexión translate, transliterate solo devuelve text y script.

[
   {
      "text":"sawatdiphuean! wannikhunthamarai",

      "script":"latn"
   }
]

Obtención de la longitud de las frases

Con el servicio Translator, puede obtener el número de caracteres de una o varias frases. La respuesta se devuelve en forma de matriz, con recuentos de caracteres por cada frase detectada. La longitud de las frases se puede obtener con los puntos de conexión translate y breaksentence.

Obtención de la longitud de las frases durante su traducción

Para obtener el recuento de los caracteres tanto del texto de origen como de la salida traducida, utilice el punto de conexión translate. Para devolver la longitud de la frase (srcSenLen y transSenLen) debe establecer el parámetro includeSentenceLength en True.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Include sentence length details.
        string route = "/translate?api-version=3.0&to=es&includeSentenceLength=true";
        string sentencesToCount =
                "Can you tell me how to get to Penn Station? Oh, you aren't sure? That's fine.";
        object[] body = new object[] { new { Text = sentencesToCount } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta. Además del idioma de origen detectado y la traducción, obtendrá el número de caracteres de todas las frases detectadas, tanto de origen (srcSentLen) como traducidas (transSentLen).

[
   {
      "detectedLanguage":{
         "language":"en",
         "score":1.0
      },
      "translations":[
         {
            "text":"¿Puedes decirme cómo llegar a Penn Station? Oh, ¿no estás seguro? Está bien.",
            "to":"es",
            "sentLen":{
               "srcSentLen":[
                  44,
                  21,
                  12
               ],
               "transSentLen":[
                  44,
                  22,
                  10
               ]
            }
         }
      ]
   }
]

Obtención de la longitud de las frases sin traducción

El servicio Translator también permite solicitar la solicitud de las frases sin su traducción. Para ello, se debe usar el punto de conexión breaksentence.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Only include sentence length details.
        string route = "/breaksentence?api-version=3.0";
        string sentencesToCount =
                "Can you tell me how to get to Penn Station? Oh, you aren't sure? That's fine.";
        object[] body = new object[] { new { Text = sentencesToCount } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta. A diferencia de la llamada al punto de conexión translate, breaksentence solo devuelve los recuentos de caracteres del texto de origen en una matriz denominada sentLen.

[
   {
      "detectedLanguage":{
         "language":"en",
         "score":1.0
      },
      "sentLen":[
         44,
         21,
         12
      ]
   }
]

Búsqueda en el diccionario (traducciones alternativas)

Con el punto de conexión, puede obtener traducciones alternativas de una palabra o frase. Por ejemplo, al traducir la palabra "sunshine" de en a es, este punto de conexión devuelve "luz solar", "rayos solares" y "soleamiento", "sol" y "insolación".

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // See many translation options
        string route = "/dictionary/lookup?api-version=3.0&from=en&to=es";
        string wordToTranslate = "sunlight";
        object[] body = new object[] { new { Text = wordToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta. Examinemos la respuesta con más detenimiento, ya que este ejemplo JSON es más complejo que muchos de los restantes del artículo. La matriz translations incluye una lista de traducciones. Cada uno de los objetos de la matriz incluye una puntuación de confianza (confidence), el texto optimizado de la pantalla del usuario final (displayTarget), el texto normalizado (normalizedText), la parte de voz (posTag) e información sobre la traducción anterior (backTranslations). Para más información acerca de la respuesta, consulte el artículo sobre la búsqueda en diccionario.

[
   {
      "normalizedSource":"sunlight",
      "displaySource":"sunlight",
      "translations":[
         {
            "normalizedTarget":"luz solar",
            "displayTarget":"luz solar",
            "posTag":"NOUN",
            "confidence":0.5313,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":15,
                  "frequencyCount":702
               },
               {
                  "normalizedText":"sunshine",
                  "displayText":"sunshine",
                  "numExamples":7,
                  "frequencyCount":27
               },
               {
                  "normalizedText":"daylight",
                  "displayText":"daylight",
                  "numExamples":4,
                  "frequencyCount":17
               }
            ]
         },
         {
            "normalizedTarget":"rayos solares",
            "displayTarget":"rayos solares",
            "posTag":"NOUN",
            "confidence":0.1544,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":4,
                  "frequencyCount":38
               },
               {
                  "normalizedText":"rays",
                  "displayText":"rays",
                  "numExamples":11,
                  "frequencyCount":30
               },
               {
                  "normalizedText":"sunrays",
                  "displayText":"sunrays",
                  "numExamples":0,
                  "frequencyCount":6
               },
               {
                  "normalizedText":"sunbeams",
                  "displayText":"sunbeams",
                  "numExamples":0,
                  "frequencyCount":4
               }
            ]
         },
         {
            "normalizedTarget":"soleamiento",
            "displayTarget":"soleamiento",
            "posTag":"NOUN",
            "confidence":0.1264,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":0,
                  "frequencyCount":7
               }
            ]
         },
         {
            "normalizedTarget":"sol",
            "displayTarget":"sol",
            "posTag":"NOUN",
            "confidence":0.1239,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sun",
                  "displayText":"sun",
                  "numExamples":15,
                  "frequencyCount":20387
               },
               {
                  "normalizedText":"sunshine",
                  "displayText":"sunshine",
                  "numExamples":15,
                  "frequencyCount":1439
               },
               {
                  "normalizedText":"sunny",
                  "displayText":"sunny",
                  "numExamples":15,
                  "frequencyCount":265
               },
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":15,
                  "frequencyCount":242
               }
            ]
         },
         {
            "normalizedTarget":"insolación",
            "displayTarget":"insolación",
            "posTag":"NOUN",
            "confidence":0.064,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"heat stroke",
                  "displayText":"heat stroke",
                  "numExamples":3,
                  "frequencyCount":67
               },
               {
                  "normalizedText":"insolation",
                  "displayText":"insolation",
                  "numExamples":1,
                  "frequencyCount":55
               },
               {
                  "normalizedText":"sunstroke",
                  "displayText":"sunstroke",
                  "numExamples":2,
                  "frequencyCount":31
               },
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":0,
                  "frequencyCount":12
               },
               {
                  "normalizedText":"solarization",
                  "displayText":"solarization",
                  "numExamples":0,
                  "frequencyCount":7
               },
               {
                  "normalizedText":"sunning",
                  "displayText":"sunning",
                  "numExamples":1,
                  "frequencyCount":7
               }
            ]
         }
      ]
   }
]

Ejemplos de diccionario (traducciones en contexto)

Una vez realizada una búsqueda en el diccionario, pase tanto el texto de origen como la traducción al punto de conexión dictionary/examples para obtener una lista de ejemplos que muestran ambos términos en el contexto de una oración o una frase. Basándose en el ejemplo anterior, usará normalizedText y normalizedTarget de la respuesta de la búsqueda en el diccionario como text y translation, respectivamente. Los parámetros de idioma de origen (from) y destino de salida (to) son obligatorios.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // See examples of terms in context
        string route = "/dictionary/examples?api-version=3.0&from=en&to=es";
        object[] body = new object[] { new { Text = "sunlight",  Translation = "luz solar" } } ;
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Si realiza una llamada correcta, debería ver la siguiente respuesta. Para más información acerca de la respuesta, consulte el artículo sobre la búsqueda en diccionario.

[
   {
      "normalizedSource":"sunlight",
      "normalizedTarget":"luz solar",
      "examples":[
         {
            "sourcePrefix":"You use a stake, silver, or ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Se usa una estaca, plata, o ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"A pocket of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Una bolsa de ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"There must also be ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"También debe haber ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"We were living off of current ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Estábamos viviendo de la ",
            "targetTerm":"luz solar",
            "targetSuffix":" actual."
         },
         {
            "sourcePrefix":"And they don't need unbroken ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Y ellos no necesitan ",
            "targetTerm":"luz solar",
            "targetSuffix":" ininterrumpida."
         },
         {
            "sourcePrefix":"We have lamps that give the exact equivalent of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Disponemos de lámparas que dan el equivalente exacto de ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"Plants need water and ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Las plantas necesitan agua y ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"So this requires ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Así que esto requiere ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"And this pocket of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":" freed humans from their ...",
            "targetPrefix":"Y esta bolsa de ",
            "targetTerm":"luz solar",
            "targetSuffix":", liberó a los humanos de ..."
         },
         {
            "sourcePrefix":"Since there is no ",
            "sourceTerm":"sunlight",
            "sourceSuffix":", the air within ...",
            "targetPrefix":"Como no hay ",
            "targetTerm":"luz solar",
            "targetSuffix":", el aire atrapado en ..."
         },
         {
            "sourcePrefix":"The ",
            "sourceTerm":"sunlight",
            "sourceSuffix":" shining through the glass creates a ...",
            "targetPrefix":"La ",
            "targetTerm":"luz solar",
            "targetSuffix":" a través de la vidriera crea una ..."
         },
         {
            "sourcePrefix":"Less ice reflects less ",
            "sourceTerm":"sunlight",
            "sourceSuffix":", and more open ocean ...",
            "targetPrefix":"Menos hielo refleja menos ",
            "targetTerm":"luz solar",
            "targetSuffix":", y más mar abierto ..."
         },
         {
            "sourcePrefix":"",
            "sourceTerm":"Sunlight",
            "sourceSuffix":" is most intense at midday, so ...",
            "targetPrefix":"La ",
            "targetTerm":"luz solar",
            "targetSuffix":" es más intensa al mediodía, por lo que ..."
         },
         {
            "sourcePrefix":"... capture huge amounts of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":", so fueling their growth.",
            "targetPrefix":"... capturan enormes cantidades de ",
            "targetTerm":"luz solar",
            "targetSuffix":" que favorecen su crecimiento."
         },
         {
            "sourcePrefix":"... full height, giving more direct ",
            "sourceTerm":"sunlight",
            "sourceSuffix":" in the winter.",
            "targetPrefix":"... altura completa, dando más ",
            "targetTerm":"luz solar",
            "targetSuffix":" directa durante el invierno."
         }
      ]
   }
]

Solución de problemas

Códigos de estado HTTP comunes

Código de estado HTTP Descripción Posible motivo
200 Aceptar La solicitud fue correcta.
400 Bad Request Falta un parámetro requerido, está vacío o es nulo. O bien, el valor pasado a un parámetro obligatorio u opcional no es válido. Un problema común es que el encabezado sea demasiado largo.
401 No autorizado La solicitud no está autorizada. Asegúrese de que la clave o el token sean válidos y estén en la región correcta. Consulte tambiénAutenticación.
429 Demasiadas solicitudes Ha superado la cuota o la tasa de solicitudes permitidas para su suscripción.
502 Puerta de enlace incorrecta Problema de red o de servidor. Podría indicar también encabezados no válidos.

Usuarios de Java

Si tiene problemas de conexión, puede ser debido a que ha expirado el certificado TLS/SSL. Para resolver este problema, instale DigiCertGlobalRootG2.crt en su almacén privado.

Pasos siguientes

Personalización y mejora de una traducción