Biblioteca cliente Azure Document Translation para JavaScript - versão 1.0.0

A Tradução de Documentos é um recurso de tradução automática baseado em nuvem do serviço Tradutor de IA do Azure. Você pode traduzir múltiplos documentos complexos para todos os idiomas e dialetos suportados, preservando a estrutura original do documento e o formato dos dados. A API de Tradução de Documento dá suporte a dois processos de tradução:

A tradução assíncrona em lote aceita o processamento de vários documentos e arquivos grandes. O processo de tradução em lote exige uma conta de armazenamento de Blobs do Azure com contêineres de armazenamento para seus documentos originais e traduzidos.

A tradução síncrona de um único arquivo suporta o processamento de traduções de arquivo único. O processo de tradução de arquivo não requer uma conta de armazenamento de Blobs do Azure. A resposta final contém o documento traduzido e é retornada diretamente para o cliente que fez a chamada.

As seguintes operações são suportadas pelo recurso de Tradução de Documentos:

  • Tradução síncrona de documentos: Usada para traduzir síncronamente um único documento. O método não requer uma conta de armazenamento de Blobs do Azure.
  • Iniciar tradução em lote: Usado para executar uma solicitação de tradução em lote assíncrona. O método requer uma conta de armazenamento de Blobs do Azure com contêineres de armazenamento para seus documentos de origem e traduzidos.
  • Obter status para todos os trabalhos de tradução: Usado para solicitar uma lista e o status de todos os trabalhos de tradução enviados pelo usuário (associados ao recurso).
  • Obtenha status para um trabalho específico de tradução: Usado para solicitar o status de um trabalho específico de tradução. A resposta inclui o status geral do trabalho e o status dos documentos que estão sendo traduzidos como parte desse trabalho.
  • Obtenha o status de todos os documentos: Usado para solicitar o status de todos os documentos em um trabalho de tradução.
  • Obter status para um documento específico: Retorna o status de um documento específico em um trabalho, conforme indicado na solicitação pelos parâmetros de consulta id e documentId.
  • Cancelar tradução: Cancela um trabalho de tradução que está sendo processado ou em fila (pendente). Uma operação não será cancelada se já tiver sido concluída, tiver falhado ou ainda estiver sendo cancelada.
  • Obter formatos suportados: Retorna uma lista de formatos de documentos ou glossários suportados pelo recurso de Tradução de Documentos.

Links de chave:

Como começar

Ambientes com suporte no momento

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

Instalar o pacote @azure/ai-translation-document

Instale a biblioteca cliente Azure Document Translation para JavaScript com npm:

npm install @azure/ai-translation-document

Configurar Armazenamento de Blobs do Azure account

A tradução em lote requer uma conta Armazenamento de Blobs do Azure. Para mais informações sobre como criar uma conta no Armazenamento de Blobs do Azure, veja aqui. Para criar contêineres para seus arquivos de origem e alvo, veja aqui. Certifique-se de autorizar o acesso ao armazenamento de recursos da sua Tradução, mais informações aqui.

Quando "Permitir Acesso à Chave da Conta de Armazenamento" está desativado na conta de armazenamento, a Identidade Gerenciada é ativada no recurso Tradutor, e ele recebe o papel "Contribuidor de Dados do Blob de Armazenamento" na conta de armazenamento, então você pode usar diretamente as URLs dos contêineres e nenhum URI SAS precisará ser gerado.

Autenticar o cliente

Esta biblioteca expõe dois clientes:

  • DocumentTranslationClient para operações de tradução em lote e status de tradução.
  • SingleDocumentTranslationClient para tradução síncrona de documento único.

Ambos os clientes podem autenticar com uma credencial Microsoft Entra ou uma chave API.

Usando uma credencial Microsoft Entra

Você pode autenticar com o Microsoft Entra ID usando uma credencial da biblioteca @azure/identity. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o pacote @azure/identity:

npm install @azure/identity

Você também precisará registrar um novo aplicativo Microsoft Entra e conceder acesso ao recurso Tradutor atribuindo um papel adequado ao seu principal de serviço.

Usando ambientes Node.js e semelhantes a Node, você pode usar a DefaultAzureCredential classe para autenticar o cliente:

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());

Para ambientes de navegador, use o InteractiveBrowserCredential pacote from @azure/identity para autenticar:

import { InteractiveBrowserCredential } from "@azure/identity";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new DocumentTranslationClient("<endpoint>", credential);

Usando uma chave API

Você também pode autenticar com a chave API do recurso usando um KeyCredential:

import { KeyCredential } from "@azure/core-auth";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const credential: KeyCredential = { key: "YOUR_SUBSCRIPTION_KEY" };
const client = new DocumentTranslationClient(endpoint, credential);

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

Conceitos principais

DocumentTranslationClient

DocumentTranslationClient é a interface para tradução em lote assíncrona e para consultas de tradução e status de documentos. A tradução em lote requer uma conta Armazenamento de Blobs do Azure com contêineres para seus documentos fonte e traduzidos.

ClienteSingleDocumentTranslation

SingleDocumentTranslationClient é a interface para a tradução síncrona de documento único. Não é necessário ter uma conta do Armazenamento de Blobs do Azure; o documento traduzido é retornado diretamente na resposta.

Exemplos

A seção a seguir fornece vários trechos de código cobrindo as principais funcionalidades dessa biblioteca cliente.

Tradução de documento síncrono

Usado para traduzir síncronicamente um único documento. O método não requer uma conta de armazenamento de Blobs do Azure.

import { SingleDocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";
import { writeFile } from "node:fs/promises";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new SingleDocumentTranslationClient(endpoint, new DefaultAzureCredential());
const response = await client.translate("hi", {
  document: {
    contents: "This is a test.",
    contentType: "text/html",
    filename: "test-input.txt",
  },
});
if (response.readableStreamBody) {
  await writeFile("test-output.txt", response.readableStreamBody);
}

Tradução de documentos em lote

Usado para executar uma solicitação de tradução em lote assíncrona. O método requer uma conta de armazenamento de Blobs do Azure com contêineres de armazenamento para seus documentos de origem e traduzidos. Forneça as URLs de contêiner de origem e destino (com tokens SAS, se necessário) e faça a consulta até a conclusão da operação.

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const poller = client.startTranslation({
  inputs: [
    {
      source: { sourceUrl: "<source container SAS URL>" },
      targets: [{ targetUrl: "<target container SAS URL>", language: "fr" }],
    },
  ],
});
const result = await poller.pollUntilDone();
console.log(`Translation status: ${result.status}`);

Obtenha formatos suportados

Retorna uma lista de formatos de documentos suportados pelo recurso de Tradução de Documentos.

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const formats = await client.getSupportedFormats("Document");
for (const format of formats.value) {
  console.log(format.format);
}

Solução de problemas

Registro em log

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode consultar os documentos do pacote @azure/logger.

Contributing

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

  • do SDK do Microsoft Azure para JavaScript
  • Last updated on