Share via

Biblioteca cliente de Batch Document Translation

  • Artículo

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.

Importante

  • La traducción de documentos se admite actualmente solo en el recurso de Translator (servicio único) y no se incluye en los servicios de Azure AI (multiservicio).

  • La traducción de documentos se admite en los niveles de pago. Language Studio solo admite los niveles de instancia S1 o D3. Se recomienda seleccionar Estándar S1 para probar la traducción de documentos. ConsultePrecios de los servicios de Azure AI: Translator.

Requisitos previos

Para empezar, necesitará lo siguiente:

Autorización de contenedor de almacenamiento

Puede elegir una de las siguientes opciones para autorizar el acceso al recurso de Translator.

✔️ Identidad administrada. La identidad administrada de Azure es una entidad de servicio que crea una identidad de Microsoft Entra y permisos específicos para los recursos administrados de Azure. Las identidades administradas permiten ejecutar la aplicación Translator sin tener que insertar credenciales en el código. Las identidades administradas son una manera más segura de conceder acceso a los datos de almacenamiento y reemplazar el requisito de incluir tokens de firma de acceso compartido (SAS) con las direcciones URL de origen y destino.

Para obtener información, veaIdentidades administradas para la traducción de documentos.

Screenshot of managed identity flow (RBAC).

Una firma de acceso compartido (SAS). Una firma de acceso compartido es una dirección URL que concede acceso restringido durante un período de tiempo especificado al servicio Translator. Para usar este método, tendrá que crear tokens de firma de acceso compartido (SAS) para los contenedores de origen y destino. Los elementos sourceUrl y targetUrl 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.

  • El contenedor de origen o blob debe designar acceso de lectura y de lista.
  • El destino contenedor o blob debe designar escritura y acceso.

Para más información, consulteCreación de tokens de SAS.

Screenshot of a resource URI with a SAS token.

Compilación de la aplicación

Hay varias herramientas disponibles para crear, compilar y ejecutar aplicaciones de Translator en C# o .NET. Aquí le guiaremos a través del uso de la interfaz de línea de comandos (CLI) o Visual Studio. Seleccione una de las siguientes pestañas para empezar:

Configuración del proyecto

En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre batch-document-translation. Este comando crea un sencillo proyecto "Hola mundo" de C# con un solo archivo de origen: Program.cs.

dotnet new console -n batch-document-translation

Cambie el directorio a la carpeta de aplicaciones recién creada. Compile la aplicación con el comando siguiente:

dotnet build

La salida de la compilación no debe contener advertencias ni errores.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Instalación de la biblioteca cliente

En el directorio de la aplicación, instale la biblioteca cliente de traducción de documentos para .NET:

dotnet add package Azure.AI.Translation.Document --version 1.0.0

Traducción de un documento o archivos por lotes

  1. Para este proyecto, necesita un documento de origen cargado en el contenedor de origen. Para ese inicio rápido puede descargar nuestro documento de ejemplo de traducción de documentos. El idioma de origen es inglés.

  2. En el directorio del proyecto, abra el archivo Program.cs en el editor o IDE que prefiera. Elimine el código preexistente, incluida la línea Console.WriteLine("Hello World!").

  3. En la clase Program.cs de la aplicación, cree variables para la clave y el punto de conexión personalizados. Para más información, consulteRecuperación de la clave y punto de conexión de dominio personalizado.

    private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

  4. Para iniciar una operación de traducción de uno o varios documentos en un único contenedor de blobs, deberá llamar al método StartTranslationAsync.

  5. Para llamar a StartTranslationAsync deberá inicializar un objeto DocumentTranslationInput que contenga los parámetros sourceUri, targetUri y targetLanguageCode:

    • Para Autorización de identidad administrada, cree estas variables:

      • sourceUri. URL para el contenedor de origen que contiene los documentos que se van a traducir.

      • targetUri la URL para el contenedor de destino en el que se escribirán los documentos traducidos.

      • targetLanguageCode. Código de idioma de los documentos traducidos. Puede encontrar códigos de idioma en nuestra página de Soporte técnico de idioma.

        Para buscar las direcciones URL de origen y destino, vaya a la cuenta de almacenamiento en Azure Portal. En la barra lateral izquierda, en Almacenamiento de datos, seleccione Contenedores y siga estos pasos para recuperar los documentos de origen y el contenedor de destino URLS.

        Source Destino
        1. Seleccione la casilla situada junto al contenedor de origen 1. Seleccione la casilla situada junto al contenedor de destino.
        2. En el área principal de la ventana, seleccione los archivos o documentos para la traducción. 2. Seleccione los puntos suspensivos situados a la derecha y, después, elija Propiedades.
        3. La dirección URL de origen se encuentra en la parte superior de la lista Propiedades. 3. La dirección URL de destino se encuentra en la parte superior de la lista Propiedades.

    • Para la autorización de firma de acceso compartido (SAS), cree estas variables

      • sourceUri. El URI de SAS, con un token de SAS anexado como una cadena de consulta, para que el contenedor de origen que contenga documentos se traduzca.
      • targetUri El URI de SAS, con un token de SAS anexado como una cadena de consulta, para el contenedor de destino en el que se escriben los documentos traducidos.
      • targetLanguageCode. Código de idioma de los documentos traducidos. Puede encontrar códigos de idioma en nuestra página de Soporte técnico de idioma.

Ejemplo de código

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 los servicios de Azure AI.

Escriba el código de ejemplo en el archivo Program.cs de la aplicación:


using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Ejecución de la aplicación

Una vez que haya agregado el ejemplo de código a la aplicación, ejecute la aplicación desde el directorio del proyecto escribiendo el siguiente comando en el terminal:

  dotnet run

Este es un fragmento de la salida esperada:

Screenshot of the Visual Studio Code output in the terminal window.

Eso es todo. Ha creado un programa para traducir documentos en un contenedor de almacenamiento mediante la biblioteca cliente de .NET.

Configuración del proyecto

Asegúrese de que esté instalada la versión más reciente de Python.

Instalación de la biblioteca cliente

Instale la versión más reciente de la biblioteca cliente de traducción de documentos:

pip install azure-ai-translation-document==1.0.0

Traducción de un documento o archivos por lotes

  1. Para este proyecto, necesita un documento de origen cargado en el contenedor de origen. Para ese inicio rápido puede descargar nuestro documento de ejemplo de traducción de documentos. El idioma de origen es inglés.

  2. En el archivo de aplicación de Python, cree variables para la clave de recurso y el punto de conexión personalizado. Para más información, consulteRecuperación de la clave y punto de conexión de dominio personalizado.

key = "<your-key>"
endpoint = "<your-custom-endpoint>"

  1. Inicialice un objeto DocumentTranslationClient que contiene los parámetros endpoint y key.

  2. Llame al método begin_translation y pase los parámetros sourceUri, targetUri y targetLanguageCode.

    • Para Autorización de identidad administrada, cree estas variables:

      • sourceUri. URL para el contenedor de origen que contiene los documentos que se van a traducir.

      • targetUri la URL para el contenedor de destino en el que se escribirán los documentos traducidos.

      • targetLanguageCode. Código de idioma de los documentos traducidos. Puede encontrar códigos de idioma en nuestra página de Soporte técnico de idioma.

        Para buscar las direcciones URL de origen y destino, vaya a la cuenta de almacenamiento en Azure Portal. En la barra lateral izquierda, en Almacenamiento de datos, seleccione Contenedores y siga estos pasos para recuperar los documentos de origen y el contenedor de destino URLS.

        Source Destino
        1. Seleccione la casilla situada junto al contenedor de origen 1. Seleccione la casilla situada junto al contenedor de destino.
        2. En el área principal de la ventana, seleccione los archivos o documentos para la traducción. 2. Seleccione los puntos suspensivos situados a la derecha y, después, elija Propiedades.
        3. La dirección URL de origen se encuentra en la parte superior de la lista Propiedades. 3. La dirección URL de destino se encuentra en la parte superior de la lista Propiedades.

    • Para la autorización de firma de acceso compartido (SAS), cree estas variables

      • sourceUri. El URI de SAS, con un token de SAS anexado como una cadena de consulta, para que el contenedor de origen que contenga documentos se traduzca.
      • targetUri El URI de SAS, con un token de SAS anexado como una cadena de consulta, para el contenedor de destino en el que se escriben los documentos traducidos.
      • targetLanguageCode. Código de idioma de los documentos traducidos. Puede encontrar códigos de idioma en nuestra página de Soporte técnico de idioma.

Ejemplo de código

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 los servicios de Azure AI.

Escriba el ejemplo de código siguiente en la aplicación de Python:


#  import libraries
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = "<your-key>"
endpoint = "<your-custom-endpoint>"
sourceUri = "<your-container-sourceUrl>"
targetUri = "<your-container-targetUrl>"
targetLanguage = "<target-language-code>"


# initialize a new instance of the DocumentTranslationClient object to interact with the Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

print("Status: {}".format(poller.status()))
print("Created on: {}".format(poller.details.created_on))
print("Last updated on: {}".format(poller.details.last_updated_on))
print(
    "Total number of translations on documents: {}".format(
        poller.details.documents_total_count
    )
)

print("\nOf total documents...")
print("{} failed".format(poller.details.documents_failed_count))
print("{} succeeded".format(poller.details.documents_succeeded_count))

for document in result:
    print("Document ID: {}".format(document.id))
    print("Document status: {}".format(document.status))
    if document.status == "Succeeded":
        print("Source document location: {}".format(document.source_document_url))
        print(
            "Translated document location: {}".format(document.translated_document_url)
        )
        print("Translated to language: {}\n".format(document.translated_to))
    else:
        print(
            "Error Code: {}, Message: {}\n".format(
                document.error.code, document.error.message
            )
        )

Ejecución de la aplicación

Una vez que haya agregado el ejemplo de código al tipo de aplicación, escriba el siguiente comando en el terminal:

python asynchronous-sdk.py

Este es un fragmento de la salida esperada:

Screenshot of the Python output in the terminal window.

Eso es todo. Ha creado un programa para traducir documentos en un contenedor de almacenamiento mediante la biblioteca cliente de Python.

Paso siguiente

Más información sobre las operaciones de traducción de documentos