Introducción a la traducción de documentos

En este artículo, aprenderá a usar la traducción de documentos con métodos de la API REST HTTP. Traducción de documentos es una característica basada en la nube del servicio Azure Translator. La API de traducción de documentos permite la traducción de documentos completos al tiempo que conserva la estructura del documento de origen y el formato del texto.

Requisitos previos

Nota

  1. Por lo general, cuando se crea un recurso de Cognitive Services en Azure Portal, tiene la opción de crear una clave de suscripción de varios servicios o una clave de suscripción de un solo servicio. Sin embargo, la traducción de documentos se admite actualmente solo en el recurso de Translator (servicio único) y no se incluye en el recurso de Cognitive Services (multiservicio).
  2. La traducción de documentos solo está disponible en el plan de servicio Estándar S1 (pago por uso) o en el plan de descuento por volumen D3. Consulte los precios de Cognitive Services precios: Translator.

Para empezar, necesitará lo siguiente:

Nombre de dominio y clave de suscripción personalizados

Importante

  • Todas las solicitudes de API al servicio de traducción de documentos requieren un punto de conexión de dominio personalizado.
  • No utilizará el punto de conexión que se encuentra en la página Claves y punto de conexión del recurso en Azure Portal, ni el punto de conexión global de Translator (api.cognitive.microsofttranslator.com) para realizar solicitudes HTTP de traducción de documentos.

¿Qué es el punto de conexión de dominio personalizado?

El punto de conexión de dominio personalizado es una dirección URL con el nombre del recurso, el nombre de host y los subdirectorios de Translator:

https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0

Búsqueda del nombre de dominio personalizado

El parámetro NAME-OF-YOUR-RESOURCE (también llamado nombre de dominio personalizado) es el valor que especificó en el campo Nombre al crear el recurso de Translator.

Imagen de Azure Portal de la creación de un recurso, con los detalles de la instancia y el campo Nombre.

Obtener tu clave de suscripción

Las solicitudes al servicio Translator requieren una clave de solo lectura para autenticar el acceso.

  1. Si ha creado un recurso nuevo, seleccione Ir al recurso una vez se haya implementado. Si tiene un recurso de traducción de documentos existente, vaya directamente a la página del recurso.
  2. En el raíl izquierdo, en Administración de recursos, seleccione Claves y punto de conexión.
  3. Copie y pegue la clave de suscripción en una ubicación adecuada, como el Bloc de notas de Microsoft.
  4. Lo pegará en el código siguiente para autenticar la solicitud en el servicio de traducción de documentos.

Imagen del campo para obtener la clave de suscripción en Azure Portal.

Creación de contenedores de Azure Blob Storage

Tendrá que crear contenedores en la cuenta de Azure Blob Storage para los archivos de origen y destino.

  • Contenedor de origen. En este contenedor se cargan los archivos para su traducción (obligatorio).
  • Contenedor de destino. En este contenedor se almacenarán los archivos traducidos (obligatorio).

Nota

La traducción de documentos admite glosarios en forma de blobs en contenedores de destino (no contenedores de glosario independientes). Si quiere incluir un glosario personalizado, agréguelo al contenedor de destino e incluya glossaryUrl con la solicitud. Si el par de idiomas de traducción no existe en el glosario, no se aplicará. Consulte Traducción de documentos mediante glosarios personalizados

Creación de tokens de acceso de SAS para la traducción de documentos

Los elementos sourceUrl, targetUrl y el elemento opcional glossaryUrl deben incluir un token de firma de acceso compartido (SAS), que se anexa como una cadena de consulta. El token se puede asignar al contenedor o a blobs específicos. Consulte Creación de tokens de SAS para el proceso de traducción de documentos.

  • El contenedor o el blob de origen deben tener designado acceso de lectura y de lista.
  • El contenedor o el blob de destino deben tener designado acceso de escritura y de lista.
  • El blob de glosario debe tener acceso designado de lectura y enumeración.

Sugerencia

  • Si va a traducir varios archivos (blobs) en una operación, delegue el acceso de SAS en el nivel de contenedor.
  • Si va a traducir un único archivo (blob) en una operación, delegue el acceso de SAS en el nivel de blob.

Traducción de documentos: solicitudes HTTP

Una solicitud de traducción de documentos por lotes se envía al punto de conexión del servicio Translator mediante una solicitud POST. Si se realiza correctamente, el método POST devuelve un código de respuesta 202 Accepted y el servicio crea la solicitud por lotes.

Encabezados HTTP

En cada solicitud de API de traducción de documentos se incluyen los siguientes encabezados:

Encabezado HTTP Descripción
Ocp-Apim-Subscription-Key Requerido: el valor es la clave de suscripción de Azure para el recurso de Translator o Cognitive Services.
Content-Type Requerido: especifica el tipo de contenido de la carga. Los valores aceptados son application/json y charset=UTF-8.
Content-Length Requerido: longitud del cuerpo de la solicitud.

Propiedades del cuerpo de la solicitud POST

  • La dirección URL de la solicitud POST es POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches.
  • El cuerpo de la solicitud POST es un objeto JSON llamado inputs.
  • El objeto inputs contiene las direcciones de contenedor sourceURL y targetURL de los pares de idioma de origen y destino.
  • Los campos prefix y suffix (opcional) se usan para filtrar documentos en el contenedor, incluidas las carpetas.
  • Cuando se traduce el documento, se aplica un valor para el campo glossaries (opcional).
  • El valor de targetUrl para cada idioma de destino debe ser único.

Nota

Si ya existe un archivo con el mismo nombre en el destino, el trabajo producirá errores.

Traducción de todos los documentos de un contenedor

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traducción de un documento específico de un contenedor

  • Asegúrese de que ha especificado "storageType": "File".
  • Asegúrese de haber creado la URL de origen y el token de SAS para el blob/documento específico (no para el contenedor).
  • Asegúrese de haber especificado el nombre del archivo de destino como parte de la dirección URL de destino, aunque el token de SAS sigue siendo para el contenedor.
  • La solicitud de ejemplo siguiente muestra un único documento que se traduce en dos idiomas de destino.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

Traducción de documentos mediante glosarios personalizados

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://myblob.blob.core.windows.net/source",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://myblob.blob.core.windows.net/target",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Uso de código para enviar solicitudes de traducción de documentos

Configuración de la plataforma de codificación

  • Cree un nuevo proyecto.
  • Reemplace Program.cs por el código de C# que se muestra a continuación.
  • Establezca los valores del punto de conexión, la clave de suscripción y la dirección URL del contenedor en Program.cs.
  • Para procesar datos JSON, agregue el paquete Newtonsoft.Json mediante la CLI de .NET.
  • Ejecute el programa desde el directorio del proyecto.

Importante

Para los ejemplos de código siguientes, deberá codificar de forma rígida la clave y el punto de conexión donde se indique. Recuerde quitar la clave del código cuando haya terminado y no publicarla públicamente. Consulte Seguridad de Azure Cognitive Services para saber cómo almacenar y acceder a las credenciales de forma segura.

Es posible que tenga que actualizar los campos siguientes, en función de la operación:

  • endpoint
  • subscriptionKey
  • sourceURL
  • targetURL
  • glossaryURL
  • id (identificador del trabajo)

Búsqueda del valor de id

  • Encontrará el valor de id del trabajo en el valor de la dirección URL Operation-Location del encabezado de respuesta del método POST. El último parámetro de la dirección URL es el valor de id del trabajo de la operación:
Encabezado de respuesta Dirección URL del resultado
Operation-Location https://<NOMBRE-DEL-RECURSO>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • También puede usar una solicitud Get Jobs para recuperar el valor de id de un trabajo de traducción de documentos.

Traducción de documentos


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


    class Program
    {

        static readonly string route = "/batches";

        private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

        private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\",\"filter\":{\"prefix\": \"Demo_1/\"} }, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");

        static async Task Main(string[] args)
        {
            using HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {

                StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

                request.Method = HttpMethod.Post;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
                request.Content = content;

                HttpResponseMessage  response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;
                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine($"Status code: {response.StatusCode}");
                    Console.WriteLine();
                    Console.WriteLine($"Response Headers:");
                    Console.WriteLine(response.Headers);
                }
                else
                    Console.Write("Error");

            }

        }

    }
}

Obtención de los formatos de archivo

Recupera una lista de los formatos de archivo admitidos. Si se realiza correctamente, este método devuelve un código de respuesta 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/documents/formats";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Obtención de estado del trabajo

Obtiene el estado actual de un único trabajo y un resumen de todos los trabajos de una solicitud de traducción de documentos. Si se realiza correctamente, este método devuelve un código de respuesta 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Obtención del estado del documento

Información general breve

Recupera el estado de un documento específico de una solicitud de traducción de documentos. Si se realiza correctamente, este método devuelve un código de respuesta 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/{id}/document/{documentId}";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Eliminación de un trabajo

Información general breve

Cancela el procesamiento actual o el trabajo en cola. Solo se cancelarán los documentos para los que no se haya iniciado la traducción.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Límites del contenido

En la tabla siguiente se enumeran los límites de los datos que se envían a la traducción de documentos.

Atributo Límite
Tamaño del documento ≤40 MB
Número total de archivos. ≤1000
Tamaño total del contenido de un lote ≤250 MB
Número de idiomas de destino en un lote ≤10
Tamaño del archivo de la memoria de traducción ≤10 MB

La traducción de documentos no se puede usar para traducir documentos protegidos, como aquellos con una contraseña cifrada o con acceso restringido para copiar contenido.

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á autenticada. Asegúrese de que la clave de suscripción o el token sean válidos y de la región correcta. Al administrar la suscripción en Azure Portal, asegúrese de usar el recurso de servicio único Translator, y no el recurso multiservicios de Cognitive Services.
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.

Más información

Pasos siguientes