Azure Document Translation client library for JavaScript - version 1.0.0

문서 번역은 Azure AI 번역기 서비스의 클라우드 기반 기계 번역 기능입니다. 원본 문서 구조와 데이터 형식을 유지하면서 모든 지원되는 언어와 방언에 걸쳐 여러 복잡한 문서를 번역할 수 있습니다. 문서 번역 API는 다음 두 가지 번역 프로세스를 지원합니다.

비동기 일괄 처리 번역은 여러 문서와 대용량 파일의 처리를 지원합니다. 일괄 처리 번역 프로세스에는 원본 및 번역된 문서에 대한 스토리지 컨테이너가 포함된 Azure Blob Storage 계정이 필요합니다.

동기식 단일 파일 변환은 단일 파일 변환 처리를 지원합니다. 파일 변환 프로세스에는 Azure Blob Storage 계정이 필요하지 않습니다. 최종 응답에는 번역된 문서가 포함되어 있으며 호출 클라이언트에 직접 반환됩니다.

문서 변환 기능에서 지원하는 작업은 다음과 같습니다:

동기식 문서 번역: 단일 문서를 동기식으로 번역하는 데 사용됩니다. 이 메서드에는 Azure Blob Storage 계정이 필요하지 않습니다.
배치 변환 시작: 비동기식 배치 변환 요청을 실행하는 데 사용됩니다. 이 방법을 사용하려면 원본 및 번역된 문서에 대한 스토리지 컨테이너가 있는 Azure Blob Storage 계정이 필요합니다.
모든 번역 작업 상태 확인: 사용자가 제출한 모든 번역 작업 목록과 상태를 요청하는 데 사용됩니다(리소스와 연관됨).
특정 번역 작업의 상태 확인: 특정 번역 작업의 상태를 요청하는 데 사용되었습니다. 응답에는 전체 작업 상태 및 해당 작업의 일부로 번역되는 문서의 상태가 포함됩니다.
모든 문서의 상태 확인: 번역 작업 중 모든 문서의 상태를 요청하는 데 사용되었습니다.
특정 문서의 상태 보기: 요청에서 id와 documentId 쿼리 매개변수로 표시된 특정 문서의 상태를 반환합니다.
번역 취소: 현재 처리 중이거나 대기 중(대기 중) 번역 작업을 취소합니다. 작업이 이미 완료되었거나, 실패했거나, 여전히 취소된 경우 취소되지 않습니다.
지원되는 형식 가져오기: 문서 번역 기능에서 지원하는 문서 또는 용어집 형식 목록을 반환합니다.

키 링크:

시작하기

현재 지원되는 환경

Node.js의 LTS 버전
Safari, Chrome, Edge 및 Firefox의 최신 버전입니다.

자세한 내용은 지원 정책 참조하세요.

사전 요구 사항

Azure 구독.
기존 번역기 서비스나 Azure AI 서비스 리소스. 번역 기 만들기 자료를 참조하세요.

`@azure/ai-translation-document` 패키지 설치

JavaScriptnpm용 Azure 문서 번역 클라이언트 라이브러리를 설치하세요:

npm install @azure/ai-translation-document

Set Azure Blob Storage account

배치 변환은 Azure Blob Storage 계정이 필요합니다. Azure Blob Storage 계정 생성에 대한 자세한 내용은 여기를 참조하세요. 소스 파일과 대상 파일을 위한 컨테이너 생성에 대해서는 여기를 참고하세요. 번역 자료 저장 접근 권한을 반드시 승인하세요. 자세한 내용은 여기에서 확인하세요.

스토리지 계정에서 "Allow Storage Account Key Access"가 비활성화되고, Translator 리소스에서 관리 식별이 활성화되었으며, 저장소 계정에서 "Storage Blob Data Contributor" 역할이 할당되면, 컨테이너 URL을 직접 사용할 수 있고 SAS URI를 생성할 필요가 없습니다.

클라이언트 인증

이 라이브러리는 두 명의 고객을 노출시킵니다:

DocumentTranslationClient 배치 번역 및 번역 상태 작업을 위한 작업입니다.
SingleDocumentTranslationClient 동기식 단일 문서 변환을 위한 것입니다.

두 클라이언트 모두 Microsoft Entra 자격 증명이나 API 키로 인증할 수 있습니다.

Microsoft Entra 자격 증명 사용

Microsoft Entra ID로 @azure/identity 라이브러리의 자격 증명을 사용해 인증할 수 있습니다. 아래에 표시된 DefaultAzureCredential 공급자 또는 Azure SDK와 함께 제공되는 다른 자격 증명 공급자를 사용하려면 @azure/identity 패키지를 설치하세요.

npm install @azure/identity

또한 새로운 Microsoft Entra 애플리케이션을 등록하고, 서비스 주체에게 적절한 역할을 할당하여 번역기 자원에 대한 접근 권한을 부여해야 합니다.

Node.js 및 노드 유사 환경을 사용하여 클래스를 사용하여 DefaultAzureCredential 클라이언트를 인증할 수 있습니다:

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

브라우저 환경에서는 'from the @azure/identity package'를 사용하여 InteractiveBrowserCredential 인증하세요:

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

API 키 사용

또한 자원의 API 키 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);

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서참조하세요.

주요 개념

DocumentTranslationClient

DocumentTranslationClient 비동기 배치 번역과 번역 및 문서 상태 조회를 위한 인터페이스입니다. 배치 변환은 원본 문서와 번역된 문서를 위한 컨테이너가 있는 Azure Blob Storage 계정이 필요합니다.

단일 문서 번역 클라이언트

SingleDocumentTranslationClient 는 동기식 단일 문서 변환을 위한 인터페이스입니다. Azure Blob Storage 계정이 필요하지 않습니다; 번역된 문서는 응답에 직접 반환됩니다.

예제

다음 섹션에서는 이 클라이언트 라이브러리의 주요 기능을 다루는 여러 코드 스니펫을 제공합니다.

동기 문서 번역

단일 문서를 동기화 번역하는 데 사용되었습니다. 이 메서드에는 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);
}

배치 문서 번역

비동기 배치 변환 요청을 실행하는 데 사용되었습니다. 이 방법을 사용하려면 원본 및 번역된 문서에 대한 스토리지 컨테이너가 있는 Azure Blob Storage 계정이 필요합니다. 소스 및 대상 컨테이너 URL(필요 시 SAS 토큰 포함)을 제공하고, 작업이 완료될 때까지 폴링합니다.

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

지원되는 포맷을 받으세요

문서 변환 기능이 지원하는 문서 형식 목록을 반환합니다.

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

로깅 (로그 기록)

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 setLogLevel@azure/logger 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

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

setLogLevel("info");

로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서를 참조하세요.

기여하기

이 라이브러리에 기여하려면 기여 가이드 읽어 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

JavaScript용 Microsoft Azure SDK

피드백

이 페이지가 도움이 되었나요?

2026-08-13 에 마지막으로 업데이트됨