Partilhar via

Introdução: bibliotecas de cliente de Tradução de Documentos

  • Artigo

A Tradução de Documentos é um recurso baseado em nuvem do serviço Azure AI Translator que traduz de forma assíncrona documentos inteiros em idiomas com suporte e vários formatos de arquivo. Neste guia de início rápido, aprenda a usar a Tradução de Documentos com uma linguagem de programação de sua escolha para traduzir um documento de origem para uma linguagem de destino, preservando a estrutura e a formatação do texto.

Importante

  • Atualmente, a Tradução de Documentos tem suporte apenas no recurso Tradutor (serviço único) e não está incluída no recurso Serviços de IA do Azure (multisserviços).
  • A tradução de documentos é suportada em níveis pagos. O Language Studio suporta as camadas de instância S1 ou D3. Sugerimos que selecione Standard S1 para experimentar a Tradução de Documentos. Consulte Preços dos serviços de IA do Azure — Tradutor.
  • As versões de visualização pública da Tradução de Documentos fornecem acesso antecipado a recursos que estão em desenvolvimento ativo. Recursos, abordagens e processos podem mudar, antes da Disponibilidade Geral (GA), com base nos comentários dos usuários.
  • A versão de visualização pública das bibliotecas de cliente de Tradução de Documentos padrão para a API REST versão 2024-05-01.

Pré-requisitos

Para começar, precisa do seguinte:

  • Uma conta ativa do Azure. Se não tiver uma, poderá criar uma conta gratuita.

  • Um recurso de Tradutor de serviço único (não um recurso de serviços de IA do Azure multisserviço). Se você estiver planejando usar o recurso Tradução de Documentos com autorização de identidade gerenciada, escolha uma região geográfica, como Leste dos EUA. Selecione o Plano de Serviço Standard S1 Standard (Pay-as-you-go) ou os Planos de Desconto por Volume C2, C3, C4 ou D3.

  • Uma conta de Armazenamento de Blob do Azure. Você criará contêineres em sua conta de Armazenamento de Blobs do Azure para seus arquivos de origem e de destino:

    • Recipiente de origem. Este contentor é onde carrega os seus ficheiros para tradução (obrigatório).
    • Recipiente de destino. Este contêiner é onde seus arquivos traduzidos são armazenados (obrigatório).

Autorização de contêiner de armazenamento

Você pode escolher uma das seguintes opções para autorizar o acesso ao seu recurso do Translator.

✔️ Identidade gerenciada. Uma identidade gerenciada é uma entidade de serviço que cria uma identidade do Microsoft Entra e permissões específicas para um recurso gerenciado do Azure. As identidades gerenciadas permitem que você execute seu aplicativo Translator sem precisar incorporar credenciais em seu código. As identidades gerenciadas são uma maneira mais segura de conceder acesso aos dados de armazenamento e substituir o requisito de incluir tokens de assinatura de acesso compartilhado (SAS) com suas URLs de origem e de destino.

Para saber mais, consulte Identidades gerenciadas para tradução de documentos.

Captura de tela do fluxo de identidade gerenciado (RBAC).

✔️ Assinatura de Acesso Compartilhado (SAS). Uma assinatura de acesso compartilhado é uma URL que concede acesso restrito por um período de tempo especificado ao seu serviço de Tradutor. Para usar esse método, você precisa criar tokens SAS (Assinatura de Acesso Compartilhado) para seus contêineres de origem e destino. O sourceUrl e targetUrl deve incluir um token SAS (Assinatura de Acesso Compartilhado), anexado como uma cadeia de caracteres de consulta. O token pode ser atribuído ao seu contêiner ou blobs específicos.

  • Seu contêiner ou blob de origem deve designar acesso de leitura e lista .
  • Seu contêiner ou blob de destino deve designar acesso de gravação e lista .

Para saber mais, consulte Criar tokens SAS.

Captura de tela de um URI de recurso com um token SAS.

Compilar a aplicação

Há várias ferramentas disponíveis para criar, criar e executar aplicativos Translator C#/.NET. Aqui, nós o guiamos pelo uso da interface de linha de comando (CLI) ou do Visual Studio. Selecione uma das seguintes guias para começar:

Configure o seu projeto

Em uma janela de console (como cmd, PowerShell ou Bash), use o dotnet new comando para criar um novo aplicativo de console com o nome batch-document-translation. Este comando cria um projeto C# "Hello World" simples com um único arquivo de origem: Program.cs.

dotnet new console -n batch-document-translation

Altere seu diretório para a pasta do aplicativo recém-criada. Crie seu aplicativo com o seguinte comando:

dotnet build

A saída da compilação não deve conter avisos ou erros.

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

Instalar a biblioteca de cliente

Dentro do diretório do aplicativo, instale a biblioteca de cliente de Tradução de Documentos para .NET:

dotnet add package Azure.AI.Translation.Document --version 2.0.0-beta

Traduzir documentos de forma assíncrona

  1. Para este projeto, você precisa de um documento de origem carregado em seu contêiner de origem. Você pode baixar nosso documento de exemplo de tradução de documentos para este guia de início rápido. A língua de partida é o inglês.

  2. No diretório do projeto, abra o arquivo Program.cs em seu editor ou IDE preferido. Exclua o código pré-existente, incluindo a linha Console.WriteLine("Hello World!").

  3. No Program.cs do aplicativo , crie variáveis para sua chave e ponto de extremidade personalizado. Para obter mais informações, consulte Recuperar sua chave e ponto de extremidade de domínio personalizado.

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

  4. Chame o StartTranslationAsync método para iniciar uma operação de tradução para um ou mais documentos em um único contêiner de blob.

  5. Para chamar StartTranslationAsynco , você precisa inicializar um DocumentTranslationInput objeto que contenha os sourceUriparâmetros , targetUrie targetLanguageCode :

    • Para autorização de Identidade Gerenciada, crie estas variáveis:

      • fonteUri. A URL do contêiner de origem que contém os documentos a serem traduzidos.

      • targetUri A URL do contêiner de destino no qual os documentos traduzidos são gravados.

      • targetLanguageCode. O código do idioma para os documentos traduzidos. Você pode encontrar códigos de idioma em nossa página de suporte de idiomas .

        Para localizar suas URLs de origem e de destino, navegue até sua conta de armazenamento no portal do Azure. Na barra lateral esquerda, em Armazenamento de dados , selecione Contêineres e siga estas etapas para recuperar seus documentos de origem e contêiner URLSde destino.

        Origem Destino
        1. Marque a caixa de seleção ao lado do contêiner de origem 1. Marque a caixa de seleção ao lado do contêiner de destino.
        2. Na área da janela principal, selecione um arquivo ou documentos para tradução. 2. Selecione as reticências localizadas à direita e, em seguida, escolha Propriedades.
        3. O URL de origem está localizado na parte superior da lista de Propriedades. 3. O URL de destino está localizado no topo da lista de Propriedades.

    • Para autorização SAS (Assinatura de Acesso Compartilhado), crie estas variáveis:

      • fonteUri. O URI SAS, com um token SAS anexado como uma cadeia de caracteres de consulta, para o contêiner de origem que contém documentos a serem traduzidos.
      • targetUri O URI SAS, com um token SAS anexado como uma cadeia de caracteres de consulta, para o contêiner de destino no qual os documentos traduzidos são gravados.
      • targetLanguageCode. O código do idioma para os documentos traduzidos. Você pode encontrar códigos de idioma em nossa página de suporte de idiomas .

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca publicá-la publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Para obter mais informações, consulte Segurança dos serviços de IA do Azure.

Exemplo de código de tradução assíncrona

Insira o seguinte exemplo de código no arquivo Program.cs do seu aplicativo:


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}");
      }
    }
  }
}

Executar a aplicação

Depois de adicionar o exemplo de código ao seu aplicativo, execute seu aplicativo a partir do diretório do projeto digitando o seguinte comando no terminal:

  dotnet run

Aqui está um trecho da saída esperada:

Captura de tela da saída do Visual Studio Code na janela do terminal.

Exemplo de código de tradução síncrona

Você pode baixar nosso documento de exemplo de tradução de documentos para este guia de início rápido. A língua de partida é o 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}");
  }
}

Está feito! Você acabou de criar um programa para traduzir documentos em um contêiner de armazenamento usando a biblioteca de cliente .NET.

Configure o seu projeto

Certifique-se de que a versão mais recente do Python está instalada.

Instalar a biblioteca de cliente

Instale a versão mais recente da biblioteca de cliente de Tradução de Documentos:

  pip install azure-ai-translation-document==1.1.0b1

Traduzir arquivos em lote

  1. Para este projeto, você precisa de um documento de origem carregado em seu contêiner de origem. Você pode baixar nosso documento de exemplo de tradução de documentos para este guia de início rápido. A língua de partida é o inglês.

  2. Em seu arquivo de aplicativo Python, crie variáveis para sua chave de recurso e ponto de extremidade personalizado. Para obter mais informações, consulte Recuperar sua chave e ponto de extremidade de domínio personalizado.

key = "{your-api-key}"
endpoint = "{your-document-translation-endpoint}"

  1. Inicialize um DocumentTranslationClient objeto que contenha seus endpoint parâmetros and key .

  2. Chame o begin_translation método e passe os sourceUriparâmetros , targetUrie targetLanguageCode .

    • Para autorização de Identidade Gerenciada, crie estas variáveis:

      • fonteUri. A URL do contêiner de origem que contém os documentos a serem traduzidos.

      • targetUri A URL do contêiner de destino no qual os documentos traduzidos são gravados.

      • targetLanguageCode. O código do idioma para os documentos traduzidos. Você pode encontrar códigos de idioma em nossa página de suporte de idiomas .

        Para localizar suas URLs de origem e de destino, navegue até sua conta de armazenamento no portal do Azure. Na barra lateral esquerda, em Armazenamento de dados , selecione Contêineres e siga estas etapas para recuperar seus documentos de origem e contêiner URLSde destino.

        Origem Destino
        1. Marque a caixa de seleção ao lado do contêiner de origem 1. Marque a caixa de seleção ao lado do contêiner de destino.
        2. Na área da janela principal, selecione um arquivo ou documentos para tradução. 2. Selecione as reticências localizadas à direita e, em seguida, escolha Propriedades.
        3. O URL de origem está localizado na parte superior da lista de Propriedades. 3. O URL de destino está localizado no topo da lista de Propriedades.

    • Para autorização SAS (Assinatura de Acesso Compartilhado), crie estas variáveis:

      • fonteUri. O URI SAS, com um token SAS anexado como uma cadeia de caracteres de consulta, para o contêiner de origem que contém documentos a serem traduzidos.
      • targetUri O URI SAS, com um token SAS anexado como uma cadeia de caracteres de consulta, para o contêiner de destino no qual os documentos traduzidos são gravados.
      • targetLanguageCode. O código do idioma para os documentos traduzidos. Você pode encontrar códigos de idioma em nossa página de suporte de idiomas .

Exemplo de código de tradução assíncrona

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca publicá-la publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Para obter mais informações, consulte Segurança dos serviços de IA do Azure.

Insira o seguinte exemplo de código em seu aplicativo 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
            )
        )

Executar a aplicação

Depois de adicionar o exemplo de código ao seu aplicativo, digite o seguinte comando no terminal:

python asynchronous-sdk.py

Aqui está um trecho da saída esperada:

Captura de tela da saída Python na janela do terminal.

Exemplo de código de tradução síncrona

Você pode baixar nosso documento de exemplo de tradução de documentos para este guia de início rápido. A língua de partida é o 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()

Está feito! Você acabou de criar um programa para traduzir documentos de forma assíncrona e síncrona usando a biblioteca de cliente Python.

Próximo passo

Saiba mais sobre as operações de Tradução de Documentos