Bibliotecas de clientes do pacote de tradução de documento

  • Artigo

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

Importante

  • No entanto, atualmente, a Tradução de Documento tem suporte apenas no recurso do Tradutor (serviço único) e não está incluída no recurso dos serviços de IA do Azure (vários serviços).

  • A tradução de documentos tem suporte em camada de serviço pagas. O Language Studio só é suportado nas camadas de instância S1 ou D3. Sugerimos que você selecione Standard S1 para experimentar a Tradução de Documento. ConsultePreços dos serviços de IA do Azure: Tradutor.

Pré-requisitos

Para começar, você precisa do seguinte:

Autorização de contêiner de armazenamento

Você pode escolher uma das opções a seguir para autorizar o acesso ao recurso de Tradução.

✔️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 de Tradução sem precisar inserir credenciais em seu código. As identidades gerenciadas são uma maneira mais segura de conceder acesso aos dados de armazenamento e substituem o requisito de incluir tokens de assinatura de acesso compartilhado (SAS) com seus URLs de origem e destino.

Para saber mais, confiraIdentidades gerenciadas para Tradução de Documentos.

Screenshot of managed identity flow (RBAC).

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

  • O contêiner ou o blob de origem deve ter acesso de leitura e lista designado.
  • O contêiner ou blob de destino deve ter acesso de gravação e lista designados.

Para saber mais, confiraCriar tokens SAS.

Screenshot of a resource URI with a SAS token.

Crie seu aplicativo

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

Configurar o seu projeto

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

dotnet new console -n batch-document-translation

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

dotnet build

A saída de compilação não deve conter nenhum aviso ou erro.

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

Instalar a biblioteca de clientes

No diretório do aplicativo, instale a biblioteca de clientes de Tradução de Documento para .NET:

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

Traduzir um documento ou arquivos em lotes

  1. Neste projeto, você precisa de um documento de origem carregado no contêiner de origem. Você pode baixar nosso documento de exemplo de tradução de documento para este início rápido. O idioma de origem é o inglês.

  2. No diretório do projeto, abra o arquivo Program.cs no IDE ou no editor de sua preferência. Exclua o código preexistente, incluindo a linha Console.WriteLine("Hello World!").

  3. Na classe Programa.cs do aplicativo, crie variáveis para a chave e o ponto de extremidade personalizado. Para obter mais informações, confiraRecuperar sua chave e o ponto de extremidade de domínio personalizado.

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

  4. Para iniciar uma operação de tradução para um ou mais documentos em um só contêiner de blob, chame o método StartTranslationAsync.

  5. Para chamar StartTranslationAsync, inicialize um objeto DocumentTranslationInput que contém os parâmetrossourceUri. targetUri e targetLanguageCode:

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

      • sourceUri. O URI para o contêiner de origem que contém documentos a serem convertidos.

      • targetUri O URI para o contêiner de destino no qual os documentos traduzidos são gravados.

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

        Para localizar suas URLs de origem e 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 os documentos de origem e URLS de contêiner de destino.

        Origem Destino
        1. Marcar a caixa de seleção próxima do contêiner de origem 1. Marque a caixa de seleção próxima do contêiner de destino.
        2. Na área da janela principal, selecione um arquivo ou os documentos para tradução. 2. Selecione as reticências localizadas à direita e escolha Propriedades.
        3. A URL de origem está localizada na parte superior da lista Propriedades. 3. A URL de destino está localizada na parte superior da lista Propriedades.

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

      • sourceUri. O URI de SAS, com um token SAS acrescentado como uma cadeia de caracteres de consulta, para o contêiner de origem que contém documentos a serem traduzidos.
      • targetUri O URI de SAS, com um token SAS acrescentado 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 de idioma para os documentos traduzidos. Você pode encontrar códigos de idioma em nossa página Suporte a idioma.

Exemplo de código

Importante

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

Insira o seguinte exemplo de código no arquivo Program.cs do 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}");
      }
    }
  }
}

Execute seu aplicativo.

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

  dotnet run

Aqui está um trecho da saída esperada:

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

É isso! Você acabou de criar um programa para traduzir documentos em um contêiner de armazenamento usando a biblioteca de clientes do .NET.

Configurar o seu projeto

Verifique se a versão mais recente do Python está instalada.

Instalar a biblioteca de clientes

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

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

Traduzir um documento ou arquivos em lotes

  1. Neste projeto, você precisa de um documento de origem carregado no contêiner de origem. Você pode baixar nosso documento de exemplo de tradução de documento para este início rápido. O idioma de origem é o inglês.

  2. No arquivo de aplicativo Python, crie variáveis para a chave de recurso e o ponto de extremidade personalizado. Para obter mais informações, confiraRecuperar sua chave e o ponto de extremidade de domínio personalizado.

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

  1. Inicialize um objeto DocumentTranslationClient que contém os parâmetros endpoint e key.

  2. Chame o método begin_translation e passe os parâmetros sourceUri, targetUri e targetLanguageCode.

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

      • sourceUri. O URI para o contêiner de origem que contém documentos a serem convertidos.

      • targetUri O URI para o contêiner de destino no qual os documentos traduzidos são gravados.

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

        Para localizar suas URLs de origem e 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 os documentos de origem e URLS de contêiner de destino.

        Origem Destino
        1. Marcar a caixa de seleção próxima do contêiner de origem 1. Marque a caixa de seleção próxima do contêiner de destino.
        2. Na área da janela principal, selecione um arquivo ou os documentos para tradução. 2. Selecione as reticências localizadas à direita e escolha Propriedades.
        3. A URL de origem está localizada na parte superior da lista Propriedades. 3. A URL de destino está localizada na parte superior da lista Propriedades.

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

      • sourceUri. O URI de SAS, com um token SAS acrescentado como uma cadeia de caracteres de consulta, para o contêiner de origem que contém documentos a serem traduzidos.
      • targetUri O URI de SAS, com um token SAS acrescentado 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 de idioma para os documentos traduzidos. Você pode encontrar códigos de idioma em nossa página Suporte a idioma.

Exemplo de código

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Para obter mais informações, confira a 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-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
            )
        )

Execute seu aplicativo.

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

python asynchronous-sdk.py

Aqui está um trecho da saída esperada:

Screenshot of the Python output in the terminal window.

É isso! Você acabou de criar um programa para traduzir documentos em um contêiner de armazenamento usando a biblioteca de clientes Python.

Próxima etapa

Saiba mais sobre a operação de Tradução de Documentos