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

A Tradução de Documentos é uma funcionalidade de tradução automática baseada na cloud do serviço Tradutor de IA do Azure. Pode traduzir múltiplos documentos complexos em todas as línguas e dialetos suportados, preservando a estrutura original do documento e o formato dos dados. A API de Tradução de Documentos suporta dois processos de tradução:

A tradução assíncrona em lote suporta o processamento de vários documentos e ficheiros grandes. O processo de tradução em conjunto requer uma conta de armazenamento de Blobs do Azure com contentores de armazenamento para os seus documentos de origem e traduzidos.

A tradução síncrona de ficheiro único suporta o processamento de traduções de ficheiro único. O processo de tradução de arquivos não requer uma conta de armazenamento de Blob do Azure. A resposta final contém o documento traduzido e é devolvida diretamente ao cliente chamador.

As seguintes operações são suportadas pela funcionalidade 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 Blob do Azure.
  • Iniciar tradução em lote: Usado para executar um pedido de tradução em lote assíncrono. O método requer uma conta de armazenamento de Blob do Azure com contêineres de armazenamento para seus documentos de origem e traduzidos.
  • Obter o estado de todos os trabalhos de tradução: Usado para solicitar uma lista e o estado de todos os trabalhos de tradução submetidos pelo utilizador (associados ao recurso).
  • Obter o estatuto de um trabalho específico de tradução: Usado para solicitar o estado 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.
  • Obter o estado de todos os documentos: Usado para pedir o estado de todos os documentos num trabalho de tradução.
  • Obter o estado de um documento específico: Devolve o estado de um documento específico num trabalho, conforme indicado no pedido pelos parâmetros de consulta id e documentId.
  • Cancelar tradução: Cancela um trabalho de tradução que esteja atualmente em processamento ou em fila (pendente). Uma operação não será cancelada se já tiver sido concluída, tiver falhado ou ainda estiver cancelando.
  • Obter formatos suportados: Devolve uma lista de formatos de documentos ou glossários suportados pela funcionalidade de Tradução de Documentos.

Ligações principais:

Como Começar

Ambientes atualmente suportados

Consulte a 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 comnpm:

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 Armazenamento de Blobs do Azure, consulte aqui. Para criar contentores para os seus ficheiros de origem e destino, veja aqui. Certifique-se de autorizar o acesso ao armazenamento de recursos de tradução, mais informações aqui.

Quando "Permitir Acesso à Chave da Conta de Armazenamento" está desativado na conta de armazenamento, a Identidade Gerida está ativada no recurso Tradutor, e esta é atribuída a função "Contribuidor de Dados do Blob de Armazenamento" na conta de armazenamento, então pode usar diretamente os URLs do contentor e não será necessário gerar URIs SAS.

Autenticar o cliente

Esta biblioteca expõe dois clientes:

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

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

Utilização de uma credencial Microsoft Entra

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

npm install @azure/identity

Também terá de registar uma nova aplicação Microsoft Entra e conceder acesso ao recurso Tradutor, atribuindo um papel adequado ao seu principal de serviço.

Usando ambientes Node.js e do tipo Node, 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);

Utilização de uma chave API

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 cliente no navegador, primeiro você precisa usar um bundler. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agregação de .

Conceitos-chave

DocumentTranslationClient

DocumentTranslationClient é a interface para a tradução em lote assíncrona e para a consulta de tradução e estado do documento. A tradução em lote requer uma conta Armazenamento de Blobs do Azure com contentores para os seus documentos fonte e traduzidos.

ClienteSingleDocumentTranslation

SingleDocumentTranslationClient é a interface para a tradução síncrona de um único documento. Não requer uma conta Armazenamento de Blobs do Azure; o documento traduzido é devolvido diretamente na resposta.

Exemplos

A secção seguinte fornece vários excertos de código que cobrem as principais funcionalidades desta biblioteca cliente.

Tradução síncrona de documentos

Usado para traduzir síncronicamente um único documento. O método não requer uma conta de armazenamento de Blob 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 um pedido de tradução em lote assíncrono. O método requer uma conta de armazenamento de Blob do Azure com contêineres de armazenamento para seus documentos de origem e traduzidos. Forneça os URLs de contentores de origem e destino (com tokens SAS, se necessário) e faça sondagem até a operação terminar.

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

Devolve uma lista de formatos de documentos suportados pela funcionalidade 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);
}

Troubleshooting

Registo

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 tempo de execução 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 para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

  • Last updated on