Compartir a través de

Introducción: 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 admite los niveles de instancia S1 o D3. Se recomienda seleccionar Estándar S1 para probar la traducción de documentos. Consulte Precios de los servicios de Azure AI: traductor.
  • Las versiones preliminares públicas de traducción de documentos proporcionan acceso anticipado a las características que están en desarrollo activo. Antes de la disponibilidad general (GA), las características, los enfoques y los procesos podrían cambiar en función de los comentarios de los usuarios.
  • La versión preliminar pública de las bibliotecas cliente de traducción de documentos tiene como valor predeterminado la versión de la API de REST 2024-05-01.

Requisitos previos

Para empezar, necesitará lo siguiente:

  • Una cuenta de Azure activa. En caso de no tener ninguna, puede crear una cuenta gratuita.

  • Un recurso Translator de servicio único (no un recurso multiservicio de servicios de Azure AI). Si planea usar la característica Traducción de documentos con autorización de identidad administrada, elija una región geográfica como Este de EE. UU. Seleccione el plan de servicio estándar S1 estándar (pago por uso) o los planes de descuento multicompra de C2, C3, C4 o D3.

  • Una cuenta 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 almacenan los archivos traducidos (obligatorio).

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, vea Identidades administradas para la traducción de documentos.

Captura de pantalla de flujo de identidad administrada (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, consulte Creación de tokens de SAS.

Captura de pantalla que muestra un URI de recurso con un token de SAS.

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 2.0.0-beta

Traducir documentos de forma asincrónica

  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, consulte Recuperació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.

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.

Ejemplo de código de traducción asincrónica

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:

Captura de pantalla de la salida de Visual Studio Code en la ventana de terminal.

Ejemplo de código de traducción sincrónica

Para ese inicio rápido puede descargar nuestro documento de ejemplo de traducción de documentos. El idioma de origen es inglés.



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

class Program {

  string endpoint = "{your-document-translation-endpoint}";
  string apiKey = "{your-api-key}";
  SingleDocumentTranslationClient client = new SingleDocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

  try
  {
    string filePath = @"C:\{folder}\document.txt"
    using Stream fileStream = File.OpenRead(filePath);

    // MultipartFormFileData (string name, System.IO.Stream content, string contentType);
    var sourceDocument = new MultipartFormFileData(Path.GetFileName(filePath), fileStream, "application/vnd.openxmlformats-officedocument.wordprocessingml.document");

    DocumentTranslateContent content = new DocumentTranslateContent(sourceDocument);

    // DocumentTranslate (string targetLanguage, Azure.AI.Translation.Document.DocumentTranslateContent documentTranslateContent, string sourceLanguage = default, string category = default, bool? allowFallback = default, System.Threading.CancellationToken cancellationToken = default);
    var response = client.DocumentTranslate("de", content);

    Console.WriteLine($"Request string for translation: {requestString}");
    Console.WriteLine($"Response string after translation: {responseString}");
  }
    catch (RequestFailedException exception) {
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
  }
}

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.1.0b1

Traducción de 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, consulte Recuperación de la clave y punto de conexión de dominio personalizado.

key = "{your-api-key}"
endpoint = "{your-document-translation-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 de traducción asincrónica

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-api-key}'
endpoint = '{your-document-translation-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 asynchronous 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:

Captura de pantalla de la salida de Python en la ventana del terminal.

Ejemplo de código de traducción sincrónica

Para ese inicio rápido puede descargar nuestro documento de ejemplo de traducción de documentos. El idioma de origen es inglés.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.ai.translation.document.models import DocumentTranslateContent


def sample_single_document_translation():

    # create variables for your resource api key, document translation endpoint, and target language
    key = "<your-api-key>"
    endpoint = "<your-document-translation-endpoint>"
    target_language = "{target-language-code}"

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

    # absolute path to your document
    file_path = "C:/{your-file-path}/document-translation-sample.docx"
    file_name = os.path.path.basename(file_path)
    file_type = (
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
    print(f"File for translation: {file_name}")

    with open(file_name, "r") as file:
        file_contents = file.read()

    document_content = (file_name, file_contents, file_type)
    document_translate_content = DocumentTranslateContent(document=document_content)

    response_stream = client.document_translate(
        body=document_translate_content, target_language=target_language
    )
    translated_response = response_stream.decode("utf-8-sig")  # type: ignore[attr-defined]
    print(f"Translated response: {translated_response}")


if __name__ == "__main__":
    sample_single_document_translation()

Eso es todo. Acaba de crear un programa para traducir documentos de forma asincrónica y sincrónica mediante la biblioteca cliente de Python.

Paso siguiente

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