Contenedor: Traducir texto

Traducción del texto.

URL de la solicitud

Envíe una solicitud POST a:

POST http://localhost:{port}/translate?api-version=3.0&&from={from}&to={to}

Solicitud de ejemplo

curl -x POST "https:localhost:5000/translate?api-version=3.0&from=en&to=es" -H "Content-Type: application/json" -d "[{
'Text': 'I would really like to drive your car.'}]"

Respuesta de ejemplo

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

Parámetros de solicitud

Los parámetros de solicitud que se pasaron en la cadena de consulta son:

Parámetros obligatorios

Parámetro de consulta	Descripción	Condición
api-version	Versión de la API que el cliente solicitó. El valor debe ser 3.0.	Parámetro obligatorio
from	Especifica el idioma del texto de entrada.	Parámetro obligatorio
to	Especifica el idioma del texto de salida. Por ejemplo, utilice to=de para traducir al alemán. Es posible traducir a varios idiomas simultáneamente mediante la repetición del parámetro en la cadena de consulta. Por ejemplo, utilice to=de&to=it para traducir al alemán e italiano.	Parámetro obligatorio

• Puede consultar el servicio para translation conocer los idiomas admitidos en el ámbito.
• Consulte también Compatibilidad con el lenguaje para la transliteración.

Parámetros opcionales

Parámetro de consulta	Descripción
textType	Parámetro opcional. Define si el texto que se está traduciendo es texto sin formato o texto HTML. El código HTML debe ser un elemento completo y bien formado. Los valores posibles son plain (valor predeterminado) o html.
includeSentenceLength	Parámetro opcional. Especifica si se deben incluir los límites de oraciones del texto de entrada y el texto traducido. Los valores posibles son true o false (valor predeterminado).

Encabezados de solicitud

encabezados	Descripción	Condición
Encabezados de autenticación	Consulte las opciones disponibles para la autenticación.	Encabezado de solicitud requerido
Content-Type	Especifica el tipo de contenido de la carga. El valor aceptado es application/json; charset=UTF-8.	Encabezado de solicitud 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

Cuerpo de la solicitud

El cuerpo de la solicitud es una matriz JSON. Cada elemento de la matriz es un objeto JSON con una propiedad de cadena denominada Text, que representa la cadena que se va a traducir.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

Se aplican las siguientes limitaciones:

• La matriz puede tener como máximo 100 elementos.
• El texto completo incluido en la solicitud no puede superar los 10 000 caracteres, incluidos los espacios.

Response body

Una respuesta correcta es una matriz JSON con un resultado para cada cadena en la matriz de entrada. Un objeto del resultado incluye las siguientes propiedades:

• translations: matriz de resultados de la traducción. El tamaño de la matriz coincide con el número de idiomas de destino especificados a través del parámetro de consulta to. Cada elemento de la matriz incluye:

• to: cadena que representa el código del idioma de destino.

• text: cadena que proporciona el texto traducido.

• sentLen: objeto que devuelve los límites de las oraciones en los textos de entrada y salida.

• srcSentLen: matriz de enteros que representan las longitudes de las oraciones en el texto de entrada. La longitud de la matriz es el número de oraciones y los valores son la longitud de cada oración.

• transSentLen: matriz de enteros que representan las longitudes de las frases en el texto traducido. La longitud de la matriz es el número de oraciones y los valores son la longitud de cada oración.

  Los límites de oraciones solo se incluyen cuando el parámetro de solicitud includeSentenceLength es true.

  • sourceText: objeto con una propiedad de cadena única denominada text, que proporciona el texto de entrada en el script predeterminado del idioma de origen. La propiedad sourceText solo está presente cuando la entrada se expresa en un script que no es el habitual del idioma. Por ejemplo, si la entrada era árabe escrito en alfabeto latino, sourceText.text será el mismo texto árabe convertido al alfabeto árabe.

Encabezados de respuesta

encabezados	Descripción
X-RequestId	Valor generado por el servicio para identificar la solicitud y usarse con fines de solución de problemas.
Sistema X-MT	Especifica el tipo de sistema que se usó para la traducción en cada idioma de destino solicitado para la traducción. El valor es una lista de cadenas separadas por comas. Cada cadena indica un tipo: ▪ Custom: la solicitud incluye un sistema personalizado y se ha usado al menos un sistema personalizado durante la traducción. ▪ Team: el resto de solicitudes.

Códigos de estado de respuesta

Si se produce un error, la solicitud devuelve una respuesta de error JSON. El código de error es un número de 6 dígitos que combina el código de estado HTTP de 3 dígitos y otro número de 3 dígitos que ayuda a categorizar aún más el error. En la página de referencia de Traductor v3 pueden encontrarse los códigos de error comunes.

Ejemplos de código: traducir texto

Nota:

• Cada ejemplo se ejecuta en el localhost que especificó con el docker run comando .
• Mientras se ejecuta el contenedor, localhost apunta al propio contenedor.
• No tiene que usar localhost:5000. Puede usar cualquier puerto que aún no esté en uso en el entorno de host.

Traducción de una única entrada

En este ejemplo se muestra cómo traducir una única oración del inglés al chino simplificado.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

El cuerpo de la respuesta es:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

La matriz translations incluye un elemento, que proporciona la traducción de la parte única de texto en la entrada.

Consulta del punto de conexión de Azure AI Translator (texto)

Este es un ejemplo de solicitud HTTP de cURL mediante localhost:5000 que especificó con el docker run comando :

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"
    -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

Nota:

Si intenta la solicitud cURL POST antes de que el contenedor esté listo, obtiene una respuesta El servicio no está disponible temporalmente. Espere hasta que el contenedor esté listo e inténtelo de nuevo.

Traducción de texto mediante swagger API

Inglés ↔ Alemán

1. Vaya a la página swagger: http://localhost:5000/swagger/index.html
2. Seleccione POST /translate.
3. Haga clic en Probar.
4. Introduzca el parámetro Desde como en.
5. Introduzca el parámetro Hasta como de.
6. Introduzca el parámetro api-version como 3.0.
7. En texts, reemplace string por el siguiente código JSON.

  [
        {
            "text": "hello, how are you"
        }
  ]

Seleccione Ejecutar y las traducciones resultantes se mostrarán en Cuerpo de respuesta. Aparecerá la siguiente respuesta:

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

Traducción de texto con Python

Francés inglés ↔

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

Traducción de texto con la aplicación de consola de C#/.NET

Español inglés ↔

Inicie Visual Studio y cree una aplicación de consola. Edite el archivo *.csproj para agregar el nodo <LangVersion>7.1</LangVersion> (especifica C# 7.1). Agregue la versión 11.0.2 del paquete NuGet Newtoonsoft.Json .

En Program.cs, reemplace todo el código existente por el script siguiente:

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

Traducción de varias cadenas

Traducir varias cadenas a la vez es simplemente cuestión de especificar una matriz de cadenas en el cuerpo de la solicitud.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

La respuesta contiene la traducción de todos los fragmentos de texto exactamente en el mismo orden que en la solicitud. El cuerpo de la respuesta es:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Traducción a varios idiomas

En este ejemplo se muestra cómo traducir la misma entrada a diferentes idiomas en una sola solicitud.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

El cuerpo de la respuesta es:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Traducción de contenido con marcado y especificación de contenido traducido

Es habitual traducir el contenido que incluye marcado, como contenido de una página HTML o de un documento XML. Incluya el parámetro de consulta textType=html al traducir contenido con etiquetas. Además, a veces resulta útil para excluir contenido específico de la traducción. Puede utilizar el atributo class=notranslate para especificar contenido que debería permanecer en el idioma original. En el ejemplo siguiente, el contenido del primer elemento div no se traduce, mientras que el del segundo elemento div, sí.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

A continuación, se muestra una solicitud de ejemplo a modo ilustrativo.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

La respuesta es:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Traducción con diccionario dinámico

Si ya conoce la traducción que quiere aplicar a una palabra o frase, puede proporcionarla como marcado dentro de la solicitud. El diccionario dinámico solo es seguro para los nombres propios, como nombres de personas y nombres de productos.

El marcado que se va a proporcionar utiliza la sintaxis siguiente.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

Por ejemplo, considere la frase en inglés "The word wordomatic is a dictionary entry" (La palabra "wordomatic" es una entrada de diccionario). Para conservar la palabra wordomatic en la traducción, envíe la solicitud siguiente:

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

El resultado es el siguiente:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

Esta característica funciona del mismo modo con textType=text o con textType=html. La característica debe usarse con moderación. La mejor forma de personalización de traducción, y más adecuada, es mediante el uso de Custom Translator. Custom Translator hace un uso completo del contexto y las probabilidades estadísticas. Si creó datos de entrenamiento que muestran el trabajo o la frase en contexto, obtendrá mejores resultados. Más información acerca de Custom Translator.

Límites de solicitud

Cada solicitud de traducción está limitada a 10 000 caracteres, en todos los idiomas de destino a los que se va a traducir. Por ejemplo, si se envía una solicitud de traducción de 3000 caracteres para traducir a tres idiomas distintos, se obtiene un tamaño de solicitud de 3000 x 3=9000 caracteres, lo que satisface el límite de solicitudes. Se le cobrará por cada carácter, no por el número de solicitudes. Se recomienda enviar solicitudes más cortas.

En la siguiente tabla se muestran los límites de caracteres y elementos de matriz correspondientes a la operación translation de Translator.

Operación	Tamaño máximo del elemento de matriz	Número máximo de elementos de matriz	Tamaño máximo de la solicitud (caracteres)
translate	10 000	100	10 000

Uso de Docker Compose: Translator con contenedores compatibles

Docker Compose es una herramienta que permite configurar aplicaciones de varios contenedores mediante un único archivo YAML denominado compose.yamlnormalmente . Use el comando docker compose up para iniciar la aplicación de contenedor y el comando docker compose down para detener y quitar los contenedores.

Si ha instalado la CLI de Docker Desktop, incluye Docker Compose y sus requisitos previos. Si no tiene Docker Desktop, consulte la Introducción a la instalación de Docker Compose.

En la tabla siguiente se enumeran los contenedores auxiliares necesarios para las operaciones de traducción de texto y documentos. El contenedor de Traductor envía información de facturación a Azure mediante un recurso de Traductor de Azure AI de la cuenta de Azure.

Operación	Consulta de solicitud	Tipo de documento	Contenedores auxiliares
• Traducción de texto • Traducción de documentos	from especificado.	Documentos de Office	None
• Traducción de texto • Traducción de documentos	from no especificado. Requiere detección de idioma automática para determinar el idioma de origen.	Documentos de Office	✔️ Contenedor de Text Analytics: idioma
• Traducción de texto • Traducción de documentos	from especificado.	Documentos PDF escaneados	✔️ Contenedor de Vision: lectura
• Traducción de texto • Traducción de documentos	from no especificado que requiera detección automática de idioma para determinar el idioma de origen.	Documentos PDF escaneados	✔️ Contenedor de Text Analytics: idioma ✔️ Contenedor de Vision: lectura

Imágenes y etiquetas de contenedor

Las imágenes de contenedor de servicios de Azure AI se pueden encontrar en el catálogo del Registro de artefactos Microsoft. En la tabla siguiente se muestra la ubicación de la imagen completa para la traducción de texto y documentos:

Contenedor	Ubicación de las imágenes	Notas
Traductor: traducción de texto	mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest	Puede ver la lista completa de etiquetas de versión de traducción de texto de servicios de Azure AI en MCR.
Traductor: traducción de documentos	TODO	TODO
Text Analytics: idioma	mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest	Puede ver la lista completa de etiquetas de versión de idioma de Text Analytics de servicios de Azure AI en MCR.
Vision: lectura	mcr.microsoft.com/azure-cognitive-services/vision/read:latest	Puede ver la lista completa de etiquetas de versión de lectura de Computer Vision de servicios de Azure AIOCR en MCR.

Creación de una aplicación

1. Utilice el editor o IDE que prefiera para crear un directorio para la aplicación denominado container-environment o asígnele un nombre.

2. Cree un nuevo archivo YAML denominado compose.yaml. Las extensiones .yml o .yaml se pueden usar para el archivo compose.

3. Copie y pegue el siguiente ejemplo de código YAML en el archivo compose.yaml. Reemplace {TRANSLATOR_KEY} y {TRANSLATOR_ENDPOINT_URI} por los valores de clave y punto de conexión de la instancia de Traductor de Azure Portal. Asegúrese de usar .document translation endpoint

4. El nombre de nivel superior (azure-ai-translator, azure-ai-language, azure-ai-read) es el parámetro que especifique.

5. container_name es un parámetro opcional que establece un nombre para el contenedor cuando se ejecuta, en lugar de permitir que docker compose genere un nombre.

   services:
     azure-ai-translator:
       container_name: azure-ai-translator
       image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
       environment:
           - EULA=accept
           - billing={TRANSLATOR_ENDPOINT_URI}
           - apiKey={TRANSLATOR_KEY}
           - AzureAiLanguageHost=http://azure-ai-language:5000
           - AzureAiReadHost=http://azure-ai-read:5000
       ports:
             - "5000:5000"
       azure-ai-language:
         container_name: azure-ai-language
         image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
         environment:
             - EULA=accept
             - billing={TRANSLATOR_ENDPOINT_URI}
             - apiKey={TRANSLATOR_KEY}
       azure-ai-read:
         container_name: azure-ai-read
         image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
         environment:
             - EULA=accept
             - billing={TRANSLATOR_ENDPOINT_URI}
             - apiKey={TRANSLATOR_KEY}
   

6. Abra un terminal, vaya a la carpeta container-environment e inicie los contenedores con el siguiente comando docker-compose:

   docker compose up
   

7. Para detener los contenedores, use el comando siguiente:

   docker compose down
   

   Sugerencia

   docker compose Comandos:

   • docker compose pause pone en pausa los contenedores en ejecución.
   • docker compose unpause {your-container-name} reactiva los contenedores en pausa.
   • docker compose restart reinicia todo el contenedor detenido y en ejecución con todos sus cambios anteriores intactos. Si realiza cambios en la configuración de compose.yaml, estos cambios no se actualizan con el comando docker compose restart. Debe usar el comando docker compose up para reflejar las actualizaciones y los cambios en el archivo compose.yaml.
   • docker compose ps -a enumera todos los contenedores, incluidos los que están detenidos.
   • docker compose exec permite ejecutar comandos para desasociar o establecer variables de entorno en un contenedor en ejecución.

   Para más información, consulte referencia de la CLI de Docker.

Pasos siguientes

Más información sobre la traducción de texto