Biblioteca cliente REST de DocumentTranslation para JavaScript

2024-11-16

Traducción de documentos es una característica de traducción automática basada en la nube del servicio Azure AI Translator. Puede traducir varios documentos complejos y en todos los idiomas y dialectos admitidos, a la vez que conserva la estructura original del documento y el formato de datos. La API de traducción de documentos 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.

El archivo único sincrónico admite el procesamiento de traducciones de archivos únicos. 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 compatibles con la característica traducción de documentos:

traducción de documentos sincrónica: se usa para traducir de forma sincrónica un único documento. El método no requiere una cuenta de Azure Blob Storage.
Iniciar traducción por lotes: se usa 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.
Obtener el estado de todos los trabajos de traducción: se usa para solicitar una lista y el estado de todos los trabajos de traducción enviados por el usuario (asociado al recurso).
Obtener el estado de un trabajo de traducción específico: se usa 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 usa para solicitar el estado de todos los documentos de un trabajo de traducción.
obtener el estado de un documento específico: devuelve el estado de un documento específico de un trabajo, tal como se indica en la solicitud por los parámetros de consulta id y documentId.
Cancelar traducción: esto cancela un trabajo de traducción que está procesando o en cola (pendiente) actualmente, como se indica en la solicitud por el parámetro de consulta id. No se cancela una operación si ya se ha completado, se ha producido un error o se sigue cancelando. En esos casos, se devuelve una solicitud incorrecta. Las traducciones completadas no se pueden cancelar y se cobran.
Obtener formatos admitidos: devuelve una lista de formatos de documento o glosario admitidos por la característica traducción de documentos. La lista incluye extensiones de archivo comunes y tipo de contenido si se usa la API de carga.

Vínculos clave:

código fuente
paquete de (NPM)
ejemplos de

Empezar

Entornos admitidos actualmente

Versiones LTS de Node.js
Versiones más recientes de Edge, Chrome, Safar y Firefox

Prerrequisitos

Un servicio Translator existente o un recurso de Cognitive Services. Más información sobre requisitos previos.

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

Instale la biblioteca cliente REST de traducción de documentos para JavaScript con npm:

npm install @azure-rest/ai-translation-document

Creación de un recurso del servicio Translator

Puede crear un recurso de Translator siguiendo Creación de un recurso de Translator.

Configuración de la cuenta de Azure Blob Storage

Para más información sobre cómo crear una cuenta de Azure Blob Storage, consulte aquí. Para crear contenedores para los archivos de origen y de destino, consulte aquí. Asegúrese de autorizar el acceso al almacenamiento de recursos de traducción, más información aquí.

Cuando "Permitir el acceso a la clave de la cuenta de almacenamiento" está deshabilitado en la cuenta de almacenamiento, la identidad administrada está habilitada en el recurso translator y se le asigna el rol "Colaborador de datos de storage Blob" en la cuenta de almacenamiento, puede usar las direcciones URL del contenedor directamente y no es necesario generar ningún URI de SAS.

Creación de un `DocumentTranslationClient` mediante una dirección URL de punto de conexión y una clave de API `KeyCredential`

Una vez que tenga el valor de la clave de API, cree una credencial.

const credentials = { key: apiKey ?? "" };

Con el valor del KeyCredential puede crear el DocumentTranslationClient mediante el método createClient de documentTranslationClient_class:

const client = createClient(endpoint, credentials);

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código que usan la clienty se tratan las características principales presentes en esta biblioteca cliente.

Traducción sincrónica de documentos

Se usa para traducir de forma sincrónica un único documento. El método no requiere una cuenta de Azure Blob Storage.

console.log("== Synchronous Document Translation ==");
const client = createClient(endpoint, credentials);
const options: DocumentTranslateParameters = {
  queryParameters: {
    targetLanguage: "hi",
  },
  contentType: "multipart/form-data",
  body: [
    {
      name: "document",
      body: "This is a test.",
      filename: "test-input.txt",
      contentType: "text/html",
    },
  ],
};

const response = await client.path("/document:translate").post(options);
if (isUnexpected(response)) {
  throw response.body;
}
console.log('Response code: ' + response.status + ', Response body: ' + response.body);

Traducción de documentos por lotes

Se usa 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.

console.log("== Batch Document Translation ==");
const client = createClient(endpoint, credentials);

const sourceUrl = await createSourceContainer(ONE_TEST_DOCUMENTS);
const sourceInput = createSourceInput(sourceUrl);
const targetUrl = await createTargetContainer();
const targetInput = createTargetInput(targetUrl, "fr");
const batchRequest = createBatchRequest(sourceInput, [targetInput]);

//Start translation
const batchRequests = {inputs: [batchRequest]};
const poller = await client.path("/document/batches").post({
body: batchRequests
}); 
const id = getTranslationOperationID(poller.headers["operation-location"]);
console.log('Translation started and the operationID is: ' + id);

Cancelar traducción de documentos

Esto cancela un trabajo de traducción que está procesando o en cola (pendiente) como se indica en la solicitud por el parámetro de consulta id. No se cancela una operación si ya se ha completado, se ha producido un error o se sigue cancelando. En esos casos, se devuelve una solicitud incorrecta. Las traducciones completadas no se pueden cancelar y se cobran.

console.log("== Cancel Translation ==");
const client = createClient(endpoint, credentials);

const sourceUrl = await createSourceContainer(ONE_TEST_DOCUMENTS);
const sourceInput = createSourceInput(sourceUrl);
const targetUrl = await createTargetContainer();
const targetInput = createTargetInput(targetUrl, "fr");
const batchRequest = createBatchRequest(sourceInput, [targetInput]);

//Start translation
const batchRequests = {inputs: [batchRequest]};
const poller = await client.path("/document/batches").post({
body: batchRequests
}); 
const id = getTranslationOperationID(poller.headers["operation-location"]);

//Cancel translation
await client.path("/document/batches/{id}", id).delete();

//get translation status and verify the job is cancelled, cancelling or notStarted
const response = await client.path("/document/batches/{id}", id).get();
if (isUnexpected(response)) {
  throw response.body;
}
console.log("The status after cancelling the batch operation is:" + response.body.status);

Obtener el estado de los documentos

Se usa para solicitar el estado de todos los documentos de un trabajo de traducción.

console.log("== Gets Documents Status ==");
const client = createClient(endpoint, credentials);

const sourceUrl = await createSourceContainer(ONE_TEST_DOCUMENTS);
const sourceInput = createSourceInput(sourceUrl);
const targetUrl = await createTargetContainer();
const targetInput = createTargetInput(targetUrl, "fr");
const batchRequest = createBatchRequest(sourceInput, [targetInput]);

//Start translation
const batchRequests = {inputs: [batchRequest]};
const response = await StartTranslationAndWait(client, batchRequests); 

const operationLocationUrl = response.headers["operation-location"]
const operationId = getTranslationOperationID(operationLocationUrl);

//get Documents Status
const documentResponse = await client.path("/document/batches/{id}/documents", operationId).get();
if (isUnexpected(documentResponse)) {
  throw documentResponse.body;
}

const responseBody = documentResponse.body;
for (const documentStatus of responseBody.value) {
    console.log("Document Status is: " + documentStatus.status);
    console.log("Characters charged is: " + documentStatus.characterCharged);
    break;          
}

Obtener el estado del documento

Esto devuelve el estado de un documento específico en un trabajo como se indica en la solicitud por los parámetros de consulta id y documentId.

console.log("== Get Document Status ==");
const client = createClient(endpoint, credentials);

const sourceUrl = await createSourceContainer(ONE_TEST_DOCUMENTS);
const sourceInput = createSourceInput(sourceUrl);
const targetUrl = await createTargetContainer();
const targetInput = createTargetInput(targetUrl, "fr");
const batchRequest = createBatchRequest(sourceInput, [targetInput]);

//Start translation
const batchRequests = {inputs: [batchRequest]};
const response = await StartTranslationAndWait(client, batchRequests); 
const operationLocationUrl = response.headers["operation-location"]
const operationId = getTranslationOperationID(operationLocationUrl);

//get Documents Status
const documentResponse = await client.path("/document/batches/{id}/documents", operationId).get();
if (isUnexpected(documentResponse)) {
  throw documentResponse.body;
}

const responseBody = documentResponse.body;
for (const document of responseBody.value) {
    //get document status
    const documentStatus = await client.path("/document/batches/{id}/documents/{documentId}", operationId, document.id).get();
    console.log("Document Status = " + documentStatus.status);
    const documentStatusOutput = documentStatus.body as DocumentStatusOutput;
    console.log("Document ID = " +documentStatusOutput.id);
    console.log("Document source path = " + documentStatusOutput.sourcePath);
    console.log("Document path = " + documentStatusOutput.path);
    console.log("Target language = " + documentStatusOutput.to);
    console.log("Document created dateTime = " + documentStatusOutput.createdDateTimeUtc);
    console.log("Document last action date time = " + documentStatusOutput.lastActionDateTimeUtc);        
}

Obtener el estado de las traducciones

Se usa para solicitar una lista y el estado de todos los trabajos de traducción enviados por el usuario (asociado al recurso).

console.log("== Get Translations Status ==");
  const client = createClient(endpoint, credentials);

  const sourceUrl = await createSourceContainer(ONE_TEST_DOCUMENTS);
  const sourceInput = createSourceInput(sourceUrl);
  const targetUrl = await createTargetContainer();
  const targetInput = createTargetInput(targetUrl, "fr");
  const batchRequest = createBatchRequest(sourceInput, [targetInput]);
  
  //Start translation
  const batchRequests = {inputs: [batchRequest]};
  const translationResponse = await StartTranslationAndWait(client, batchRequests); 
  const operationLocationUrl = translationResponse.headers["operation-location"]
  const operationId = getTranslationOperationID(operationLocationUrl);  

  //get Translation Statusby ID filter
  const queryParams = {
      ids: [operationId]
    };    
  const response = await client.path("/document/batches").get({
      queryParameters: queryParams 
    });
  if (isUnexpected(response)) {
    throw response.body;
  }  
  const responseBody = response.body;
  for (const translationStatus of responseBody.value) {
    console.log("Translation ID = " + translationStatus.id);
    console.log("Translation Status = " + translationStatus.status);
    console.log("Translation createdDateTimeUtc = " + translationStatus.createdDateTimeUtc);
    console.log("Translation lastActionDateTimeUtc = " + translationStatus.lastActionDateTimeUtc);
    console.log("Total documents submitted for translation = " + translationStatus.summary.total);
    console.log("Total characters charged = " + translationStatus.summary.totalCharacterCharged);
  }

Obtener estado de traducción

Se usa 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.

console.log("== Get Translation Status ==");
const client = createClient(endpoint, credentials);

const sourceUrl = await createSourceContainer(ONE_TEST_DOCUMENTS);
const sourceInput = createSourceInput(sourceUrl);
const targetUrl = await createTargetContainer();
const targetInput = createTargetInput(targetUrl, "fr");
const batchRequest = createBatchRequest(sourceInput, [targetInput]);

//Start translation
const batchRequests = {inputs: [batchRequest]};
const translationResponse = await StartTranslationAndWait(client, batchRequests); 

const operationLocationUrl = translationResponse.headers["operation-location"]
const operationId = getTranslationOperationID(operationLocationUrl);  

//get Translation Status
const response = await client.path("/document/batches/{id}",operationId).get() as GetTranslationStatus200Response;
if (isUnexpected(response)) {
    throw response.body;
}

console.log("Translation ID = " + response.body.id);
console.log("Translation Status = " + response.body.status);
console.log("Translation createdDateTimeUtc = " + response.body.createdDateTimeUtc);
console.log("Translation lastActionDateTimeUtc = " + response.body.lastActionDateTimeUtc);
console.log("Total documents submitted for translation = " + response.body.summary.total);
console.log("Total characters charged = " + response.body.summary.totalCharacterCharged);

Obtener formatos admitidos

Esto devuelve una lista de formatos de documento o glosario admitidos por la característica traducción de documentos. La lista incluye extensiones de archivo comunes y tipo de contenido si se usa la API de carga.

console.log("== List Supported Format Types ==");

const documentTranslationClient = DocumentTranslationClient(endpoint);
const response = await documentTranslationClient.path("/document/formats").get();

const fileFormatTypes = response.body;
fileFormatTypes.value.forEach((fileFormatType: { format: any; contentTypes: any; fileExtensions: any; }) => {
console.log(fileFormatType.format);
console.log(fileFormatType.contentTypes);
console.log(fileFormatType.fileExtensions);
});

Solución de problemas

Cuando interactúa con Translator Service mediante la biblioteca cliente DocumentTranslator, los errores devueltos por el servicio Translator corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de API REST.

Por ejemplo, si envía una solicitud de traducción sin un idioma de traducción de destino, se devuelve un error de 400, que indica "Solicitud incorrecta".

Puede encontrar los diferentes códigos de error devueltos por el servicio en la documentación del servicio de .

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:

const { setLogLevel } = require("@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. Consulte la documentación del servicio para obtener una explicación conceptual de [idiomas][languages_doc].