Biblioteca cliente Azure Document Translation para JavaScript - versión 1.0.0

La traducción de documentos es una función de traducción automática basada en la nube del servicio Traductor de Azure AI. Puedes traducir múltiples documentos complejos a través de todos los idiomas y dialectos soportados preservando la estructura original del documento y el formato de datos. Document Translation API admite dos procesos de traducción:

La traducción por lotes asincrónica admite el procesamiento de varios documentos y archivos grandes. El proceso de traducción por lotes requiere una cuenta de Azure Blob Storage con contenedores de almacenamiento para los documentos de origen y traducidos.

La traducción síncrona de un solo archivo soporta el procesamiento de traducciones de un solo archivo. El proceso de traducción de archivos no requiere una cuenta de Azure Blob Storage. La respuesta final contiene el documento traducido y se devuelve directamente al cliente que realiza la llamada.

Las siguientes operaciones son soportadas por la función de Traducción de Documentos:

  • Traducción síncrona de documentos: Se utiliza para traducir síncronamente un solo documento. El método no requiere una cuenta de Azure Blob Storage.
  • Iniciar traducción por lotes: Se utiliza para ejecutar una solicitud de traducción por lotes asíncrona. El método requiere una cuenta de Azure Blob Storage con contenedores de almacenamiento para los documentos de origen y traducidos.
  • Obtener el estado de todos los trabajos de traducción: Se utiliza para solicitar una lista y el estado de todos los trabajos de traducción enviados por el usuario (asociados al recurso).
  • Obtener el estado de un trabajo de traducción específico: Se usó para solicitar el estado de un trabajo de traducción específico. La respuesta incluye el estado general del trabajo y el estado de los documentos que se traducen como parte de ese trabajo.
  • Obtener el estado de todos los documentos: Se usaba para solicitar el estado de todos los documentos en un trabajo de traducción.
  • Obtener el estado de un documento específico: Devuelve el estado de un documento específico en un trabajo, tal como se indica en la solicitud por los parámetros de consulta id y documentId.
  • Cancelar traducción: Cancela un trabajo de traducción que está en proceso o en cola (pendiente). No se cancela una operación si ya se ha completado, se ha producido un error o se sigue cancelando.
  • Obtener formatos compatibles: Devuelve una lista de formatos de documentos o glosarios soportados por la función de Traducción de Documentos.

Vínculos clave:

Cómo empezar

Entornos admitidos actualmente

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerequisites

Instalación del paquete @azure/ai-translation-document

Instala la biblioteca cliente de Azure Document Translation para JavaScript con npm:

npm install @azure/ai-translation-document

Configurar Azure Blob Storage account

La traducción por lotes requiere una cuenta de Azure Blob Storage. Para más información sobre cómo crear una cuenta de Azure Blob Storage, consulta aquí. Para crear contenedores para tus archivos de origen y destino, consulta aquí. Asegúrate de autorizar el acceso a tu almacenamiento de recursos de traducción, más información aquí.

Cuando "Permitir acceso a la clave de cuenta de almacenamiento" está desactivada en la cuenta de almacenamiento, la Identidad Gestionada se habilita en el recurso traductor y se le asigna el rol "Storage Blob Data Contributor" en la cuenta de almacenamiento, entonces puedes usar directamente las URLs del contenedor y no será necesario generar URI SAS.

Autenticar el cliente

Esta biblioteca expone a dos clientes:

  • DocumentTranslationClient para operaciones de traducción por lotes y estado de traducción.
  • SingleDocumentTranslationClient para traducción síncrona de un solo documento.

Ambos clientes pueden autenticarse con una credencial de Microsoft Entra o una clave de API.

Uso de una credencial de Microsoft Entra

Puedes autenticarte con Microsoft Entra ID usando una credencial de la biblioteca @azure/identity. Para usar el proveedor de de DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el paquete de @azure/identity:

npm install @azure/identity

También tendrás que registrar una nueva aplicación Microsoft Entra y conceder acceso al recurso Traductor asignando un rol adecuado a tu director de servicio.

Usando entornos Node.js y similares a Node, puedes usar la DefaultAzureCredential clase para autenticar al 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 entornos de navegador, utiliza el InteractiveBrowserCredential paquete 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);

Uso de una clave API

También puedes autenticarte con la clave API del recurso usando un 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);

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

Conceptos clave

ClientDocumentTranslationClient

DocumentTranslationClient es la interfaz para la traducción por lotes asíncrona y para consultar traducciones y estado de documentos. La traducción por lotes requiere una cuenta de Azure Blob Storage con contenedores para tus documentos fuente y traducidos.

ClienteSingleDocumentTranslationClient

SingleDocumentTranslationClient es la interfaz para la traducción síncrona de un solo documento. No requiere una cuenta de Azure Blob Storage; el documento traducido se devuelve directamente en la respuesta.

Ejemplos

La siguiente sección proporciona varios fragmentos de código que cubren las principales características de esta biblioteca cliente.

Traducción de documentos sincrónica

Se usa para traducir síncronamente un solo documento. El método no requiere una cuenta de Azure Blob Storage.

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

Traducción por lotes de documentos

Se utiliza para ejecutar una solicitud de traducción por lotes asincrónica. El método requiere una cuenta de Azure Blob Storage con contenedores de almacenamiento para los documentos de origen y traducidos. Proporciona las URLs del contenedor de origen y destino (con tokens SAS si es necesario) y consulta hasta que la operación se complete.

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

Consigue formatos compatibles

Devuelve una lista de formatos de documentos soportados por la función de Traducción 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);
}

Solución de problemas

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Contributing

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.

  • Last updated on