Introducción: API de REST de Traducción de documentos

2025-02-05

Traducción de documentos es una característica basada en la nube del servicio Traductor de Azure AI que traduce de forma asincrónica documentos completos en los idiomas admitidos y varios formatos de archivo. En este inicio rápido, va a aprender a usar la traducción de documentos con el lenguaje de programación que prefiera para traducir un documento de origen a un idioma de destino, conservando la estructura y el formato de texto.

La API de traducción de documentos admite dos procesos de traducción:

La traducción por lotes asincrónica admite el procesamiento de varios documentos y archivos grandes. El proceso de traducción por lotes requiere una cuenta de Azure Blob Storage con contenedores de almacenamiento para los documentos de origen y traducidos.
El archivo único sincrónico admite el procesamiento de traducciones de archivos únicos. El proceso de traducción de archivos no requiere una cuenta de Azure Blob Storage. La respuesta final contiene el documento traducido y se devuelve directamente al cliente que realiza la llamada.

Comencemos.

Requisitos previos

Necesita una suscripción de Azure activa. Si no tiene una suscripción de Azure, puede crear una gratis.

Una vez que tenga la suscripción de Azure, cree un recurso del Traductor de Azure AI en Azure Portal.
Nota:
- Para este inicio rápido, se recomienda usar un recurso global de texto del Traductor de Azure AI de un solo servicio a menos que la empresa o la aplicación requieran una región específica. Si planea usar una identidad administrada asignada por el sistema para la autenticación, elija una región geográfica como Oeste de EE. UU.
- Con un recurso global de un solo servicio, se incluye un encabezado de autorización (Ocp-Apim-Subscription-key) con la solicitud de la API de REST. El valor Ocp-Apim-Subscription-key es su clave secreta de Azure para su suscripción de texto del Traductor de Azure AI.
Después de implementar el recurso, seleccione el botón Ir al recurso para obtener la clave y el punto de conexión.
- Necesita la clave y el punto final del recurso para conectar su aplicación al servicio del Traductor de Azure AI. En una sección posterior de este mismo inicio rápido, va a pegar la clave y el punto de conexión en el código. Puede encontrar estos valores en la página Claves y punto de conexión de Azure Portal.
Para este proyecto, usaremos la herramienta de línea de comandos cURL para realizar llamadas a la API REST.

Nota:

El paquete cURL está preinstalado en la mayoría de las distribuciones de Windows 10 y Windows 11 y la mayoría de las distribuciones de macOS y Linux. Puede comprobar la versión del paquete con los siguientes comandos: Windows: curl.exe -V macOS curl -V Linux: curl --version
Si cURL no está instalada, estos son los vínculos de instalación para su plataforma:
- Windows
- Mac o Linux

Traducción asincrónica de documentos (POST)

Utilice el editor o IDE que prefiera para crear un directorio para la aplicación denominado document-translation.
Cree un archivo de JSON denominado document-translation.json en el directorio document-translation.
Copie y pegue la solicitud de ejemplo de traducción de documentos en el archivo document-translation.json. Sustituya {your-source-container-SAS-URL} y {your-target-container-SAS-URL} con los valores de la instancia de contenedores de la cuenta de Storage de Azure Portal.

Solicitud de ejemplo:
```
{
  "inputs":[
    {
      "source":{
        "sourceUrl":"{your-source-container-SAS-URL}"
      },
      "targets":[
        {
          "targetUrl":"{your-target-container-SAS-URL}",
          "language":"fr"
        }
      ]
    }
  ]
}
```

Compilación y ejecución de la solicitud POST

Antes de ejecutar la solicitud POST, reemplace {your-document-translator-endpoint} y {your-key} por los valores de la instancia del Traductor de Azure AI 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, consulteSeguridad de servicios de Azure AI.

PowerShell

cmd /c curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

command prompt/terminal

curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

Tras completarse correctamente:

Los documentos traducidos se pueden encontrar en el contenedor de destino.
El método POST correcto devuelve un código de respuesta 202 Accepted que indica que el servicio ha creado la solicitud por lotes.
La solicitud POST también devuelve encabezados de respuesta, entre los que se incluye Operation-Location, que proporciona un valor utilizado en las solicitudes GET posteriores.

Traducir sincrónicamente un único documento (POST)

Para llamar a la característica de traducción sincrónica a través de la API de REST, debe incluir los siguientes encabezados con cada solicitud. No se preocupe, se incluyen los encabezados para usted en el código de ejemplo.

Nota:

Todas las marcas cURL y las opciones de línea de comandos distinguen mayúsculas de minúsculas.

Parámetro de consulta	Descripción	Condición
`-X` o `--requestPOST`	La marca -X especifica el método de solicitud para acceder a la API.	Obligatorio
`{endpoint}`	Dirección URL del punto de conexión del recurso de traducción de documentos	Obligatorio
`targetLanguage`	Especifica el idioma del documento de salida. El idioma de destino debe ser uno de los idiomas admitidos incluidos en el ámbito de traducción.	Obligatorio
`sourceLanguage`	Especifica el idioma del documento de entrada. Si no se ha especificado el parámetro `sourceLanguage`, se aplica la detección de idioma automática para determinar el idioma de origen.	Opcional
`-H` o `--header"Ocp-Apim-Subscription-Key:{KEY}`	Encabezado de solicitud que especifica la clave de recurso de traducción de documentos que autoriza el acceso a la API.	Obligatorio
`-F` o `--form`	Ruta de acceso al documento que desea incluir con la solicitud. Solo se permite un documento de origen.	Obligatorio
• `document=` • `type={contentType}/fileExtension`	• Ruta de acceso a la ubicación del archivo para el documento de origen.• Tipo de contenido y extensión de archivo. Ej: "document=@C:\Test\test-file.md;type=text/markdown	Obligatorio
`-o` o `--output`	Ruta de acceso de archivo a los resultados de la respuesta.	Obligatorio
`-F` o `--form`	Ruta de acceso a un glosario opcional que se va a incluir con la solicitud. El glosario requiere una marca de `--form` independiente.	Opcional
• `glossary=` • `type={contentType}/fileExtension`	• Ruta de acceso a la ubicación del archivo del glosario opcional.• Tipo de contenido y extensión de archivo. Ej: "glossary=@C:\Test\glossary-file.txt;type=text/plain	Opcional

✔️ Para más información sobre contentType, consulteFormatos de documento admitidos.

Compilación y ejecución de la solicitud POST sincrónica

Para este proyecto, necesita un documento de ejemplo. Puede descargar nuestro documento de ejemplo de Microsoft Word para este inicio rápido. El idioma de origen es inglés.

Antes de ejecutar la solicitud POST, reemplace {your-document-translation-endpoint} y {your-key} por los valores de la instancia del servicio de Traductor de Azure AI de Azure Portal.

Importante

command prompt/terminal


curl -i -X POST "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -H "Ocp-Apim-Subscription-Key:{your-key}"  -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension}" -F "glossary={path-to-your-glossary-with-file-extension};type={ContentType}/{file-extension}" -o "{path-to-output-file}"

PowerShell

cmd /c curl "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -i -X POST  -H "Ocp-Apim-Subscription-Key: {your-key}" -F "{path-to-your-document-with-file-extension};type=text/{file-extension}" -o "{path-to-output-file}

✔️ Para más información sobre Query parameters, consultetraducción de documentos sincrónica.

Tras completarse correctamente:

El documento traducido se devuelve con la respuesta.
El método POST correcto devuelve un código de respuesta 200 OK que indica que el servicio ha creado la solicitud.

Eso es todo, ¡enhorabuena! Acaba de aprender a traducir documentos usando el servicio Traductor de Azure AI.

Pasos siguientes

Guía de la API de REST de traducción de documentos