Iniciar traducción por lotes

Referencia
Característica: Azure Translator → Versión de la API de traducción de documentos (GA): 2024-05-01
API (versión preliminar): 2025-12-01-preview, agrega compatibilidad con la traducción
de archivos de imagen.
Método HTTP: POST

• Use el Start Translation método para ejecutar una solicitud de traducción por lotes asincrónica.
• El método requiere una cuenta de Azure Blob Storage con contenedores de almacenamiento para los documentos de origen y traducidos.

URL de la solicitud

  curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"

Encabezados de solicitud

Los encabezados de solicitud son:

BatchRequest (cuerpo)

• Cada solicitud puede contener varios documentos y debe contener un contenedor de origen y otro de destino para cada documento. Tipos de medios de origen: application/json, text/json, application/*+json.

• El filtro de prefijo y sufijo (si se proporcionan) se usan para filtrar carpetas. El prefijo se aplica a la subruta después del nombre del contenedor.

• Los glosarios se pueden incluir en la solicitud. Si el glosario no es válido o no se puede acceder a él durante la traducción, se indica un error en el estado del documento.

• Si ya existe un archivo con el mismo nombre en el destino de destino, se produce un error en el trabajo.

• El valor de targetUrl para cada idioma de destino debe ser único.

{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Entradas

Definición para la solicitud de traducción por lotes de entrada.

inputs.source

Definición de los datos de origen.

inputs.targets

Definición de los datos de destino y glosarios.

inputs.storageType

Definición de la entidad de almacenamiento para los documentos de entrada.

Opciones

Definición para la solicitud de traducción por lotes de entrada.

Solicitud de ejemplo

Los siguientes son ejemplos de solicitudes por lotes.

Traducción de todos los documentos de un contenedor

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

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

• Especifique "storageType": File.
• Cree la dirección URL de origen y el token de SAS para el blob o documento específicos.
• 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.

Esta solicitud de ejemplo muestra un único documento traducido a dos idiomas de destino.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

• Puede encontrar el valor de id del trabajo en el valor de la dirección URL start-batch-translation del encabezado de respuesta del método POST Operation-Location. La cadena alfanumérica que sigue al parámetro /document/ es el trabajo de la operación id:

  Encabezado de respuesta	Dirección URL de respuesta
  Ubicación de la Operación	{document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01

• También puede usar una solicitud get-translations-status para recuperar una lista de trabajos de traducción y sus ids.

Traducción de todos los documentos de un contenedor que aplica glosarios

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Traducción de una carpeta específica en un contenedor

Asegúrese de especificar el nombre de carpeta (distingue mayúsculas de minúsculas) como prefijo en el filtro.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traducción de archivos de imagen

Configuración de solicitudes (archivos de imagen)

Para la traducción de archivos de imagen, envíe la imagen a través de una llamada a la API REST de traducción de documentos por lotes estándar, especificando la versión de API 2025-12-01-preview. No es necesario realizar ninguna otra configuración.

Formatos admitidos (archivos de imagen)

Idiomas admitidos (archivos de imagen)

Para obtener más información sobre los idiomas admitidos, consulteCompatibilidad con idiomas de traducción de documentos.

Códigos de estado de respuesta

A continuación se indican los códigos de estado HTTP posibles que devuelve una solicitud.

Respuesta de error

Respuesta de error de ejemplo

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Pasos siguientes

Siga nuestro inicio rápido para obtener más información sobre el uso de la traducción de documentos y la biblioteca cliente.