다음을 통해 공유

동기 문서 번역

참조
기능: Azure Translator → 문서 번역
API 버전: 2024-05-01
HTTP 메서드: POST

  • 단일 문서를 동기식으로 번역하려면 translate document 메서드를 사용합니다.
  • 이 메서드에는 Azure Blob Storage 계정이 필요하지 않습니다.
  • 최종 응답은 번역된 문서를 포함하고 호출 클라이언트에 직접 반환됩니다.

중요합니다

문서 번역 기능에 대한 모든 API 요청에는 Azure Portal의 리소스 개요 페이지에 있는 사용자 지정 도메인 엔드포인트가 필요합니다.

요청 URL

https://{your-document-translation-endpoint}/translator/document:translate?api-version=2024-05-01&sourceLanguage=en&targetLanguage=fr

헤더 요청

REST API를 통해 동기 번역 기능을 호출하려면 각 요청에 다음 헤더를 포함합니다.

헤더 값 조건
Ocp-Apim-Subscription-Key Azure Portal의 Translator 키입니다. • 필수

요청 매개 변수

필수 쿼리 매개 변수

쿼리 매개 변수 설명
api-version 필수 매개 변수입니다.
클라이언트에서 요청한 API 버전입니다. 현재 값은 2024-05-01입니다.
targetLanguage 필수 매개 변수입니다.
출력 문서의 언어를 지정합니다. 대상 언어는 번역 범위에 포함된 지원 언어 중 하나여야 합니다.

선택적 쿼리 매개 변수

쿼리 매개 변수 설명
sourceLanguage 입력 문서의 언어를 지정합니다. sourceLanguage 매개 변수를 지정하지 않으면 자동 언어 검색이 적용되어 원본 언어를 결정합니다.
allowFallback • 사용자 지정 시스템이 존재하지 않을 때 서비스가 generalnn 시스템으로 대체되도록 지정하는 부울입니다. 허용되는 값은 ( true 기본값) 또는 false.
• allowFallback=false는 요청에 지정된 범주에 대해 학습된 시스템만 번역에서 사용해야 함을 지정합니다.
• 특정 범주를 사용하는 시스템이 없는 경우 요청은 400 상태 코드를 반환합니다.
• allowFallback=true는 사용자 지정 시스템이 없을 때 서비스가 generalnn 시스템으로 대체되도록 허용하도록 지정합니다.
카테고리 번역의 범주(도메인)를 지정하는 문자열입니다. 이 매개 변수를 사용하여 Custom Translator로 작성된 사용자 지정 시스템의 번역을 가져옵니다. 배포된 사용자 지정 시스템을 동시 문서 번역에 사용하려면 사용자 지정 번역기 프로젝트 세부 정보에서 Category ID을(를) category 매개변수에 추가하세요. 기본값은 generalnn입니다.

비고

선택 사항이지만 sourceLanguage 명시적으로 지정하는 것이 좋습니다. 원본 언어를 제공하면 자동 검색에 의존하는 것보다 더 나은 품질의 번역이 생성됩니다.

요청 본문

이름 설명 콘텐츠 형식 조건
문서 번역할 원본 문서입니다. 지원되는 문서 형식 중 하나입니다. 필수
용어집 번역 과정에서 사용할 정의와 용어 목록이 포함된 문서입니다. 지원되는 용어집 형식 중 하나입니다. 선택 사항

응답 상태 코드

상태 코드 설명
200 요청이 성공했고 번역된 문서가 반환됩니다.
400 요청 매개 변수가 잘못되었거나 누락되었습니다.
401 인증에 실패했습니다. 구독 키 또는 토큰을 확인합니다.
429 속도 제한을 초과했습니다. 잠시 후 다시 시도합니다.
500 예기치 않은 서비스 오류입니다. 요청 세부 정보를 사용하여 지원을 다시 시도하거나 문의하세요.
503 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오.

비고

오류는 error 개체를 포함하는 JSON 응답을 반환합니다.

예제 JSON 오류 응답

{
  "error": {
    "code": "InvalidRequest",
    "message": "The 'targetLanguage' parameter is required.",
    "innerError": {
      "requestId": "d3e4f6a9-0000-4a9b-8ad3-bdcd1323aa00",
      "date": "2025-10-15T10:05:23Z"
    }
  }
}

Word 문서 번역

curl --request POST \
  --url 'https://{your-document-translation-endpoint}/translator/document:translate?api-version=2024-05-01&sourceLanguage=en&targetLanguage=fr' \
  --header 'Ocp-Apim-Subscription-Key: <your-subscription-key>' \
  --form 'document=@<path-to-your-document>/your-document-file.docx' \
  --output translated-document-fr.docx

매개 변수

매개 변수 설명
{your-document-translation-endpoint} 문서 번역 엔드포인트입니다. 예: https://your-resource-name.cognitiveservices.azure.com
<your-subscription-key> Translator 구독 키입니다.
sourceLanguage (선택 사항) 소스 언어 코드입니다. 예: en. 지정하지 않으면 자동으로 검색됩니다.
targetLanguage (필수) 번역할 대상 언어 코드입니다. 예: fr.
document 번역할 파일의 경로입니다.

자세한 내용은 지원되는 문서 형식을 참조하세요.

용어집을 사용하여 Word 문서 번역

curl --request POST \
  --url 'https://{your-document-translation-endpoint}/translator/document:translate?api-version=2024-05-01&sourceLanguage=en&targetLanguage=fr' \
  --header 'Ocp-Apim-Subscription-Key: <your-subscription-key>' \
  --form 'document=@<path-to-your-document>/your-document-file.docx' \
  --form 'glossary=@<path-to-your-document>/glossary.tsv' \
  --output translated-document-fr.docx

매개 변수

매개 변수 설명
{your-document-translation-endpoint} 문서 번역 엔드포인트입니다. 예: https://your-resource-name.cognitiveservices.azure.com
<your-subscription-key> Translator 구독 키입니다.
sourceLanguage (선택 사항) 소스 언어 코드입니다. 예: en. 지정하지 않으면 자동으로 검색됩니다.
targetLanguage (필수) 번역할 대상 언어 코드입니다. 예: fr.
document 번역할 파일의 경로입니다.
glossary 용어집 파일의 경로입니다.

자세한 내용은 문서 번역과 함께 용어집 사용을참조하세요.

다음 단계

문서 번역 빠른 시작 시도

  • Last updated on