다음을 통해 공유

시작: 문서 번역 클라이언트 라이브러리

  • 아티클

문서 번역은 지원되는 언어 및 다양한 파일 형식으로 전체 문서를 비동기식으로 번역하는 Azure AI 번역기 서비스의 클라우드 기반 기능입니다. 이 빠른 시작에서는 선택한 프로그래밍 언어와 함께 문서 번역을 사용하여 구조 및 텍스트 서식을 유지하면서 원본 문서를 대상 언어로 번역하는 방법을 알아봅니다.

Important

  • 문서 번역은 현재 번역기(단일 서비스) 리소스에서만 지원되며, Azure AI 서비스(다중 서비스) 리소스에는 포함되지 않습니다.
  • 문서 번역은 유료 계층에서 지원됩니다. Language Studio는 S1 또는 D3 인스턴스 계층을 지원합니다. 문서 번역을 시도하려면 표준 S1을 선택하는 것이 좋습니다. Azure AI 서비스 가격 책정 - 번역기를 참조하세요.
  • 문서 번역 공개 미리 보기 릴리스는 현재 개발 중인 기능에 대한 조기 액세스를 제공합니다. 기능, 방식 및 프로세스는 GA(일반 공급) 전에 사용자 피드백에 따라 변경될 수 있습니다.
  • 문서 번역 클라이언트 라이브러리의 공개 미리 보기 버전은 기본적으로 REST API 버전 2024-05-01입니다.

필수 조건

시작하려면 다음이 필요합니다.

  • 활성 Azure 계정. 계정이 없는 경우 무료 계정에 만들 수 있습니다.

  • 단일 서비스 번역기 리소스(다중 서비스 Azure AI 서비스 리소스가 아님): 관리 ID 인증으로 문서 번역 기능을 사용하려면 미국 동부와 같은 지리적 지역을 선택합니다. 표준 S1 표준 서비스 계획(종량제) 또는 C2, C3, C4 또는 D3 볼륨 할인 계획을 선택합니다.

  • Azure Blob Storage 계정 원본 및 대상 파일에 대한 Azure Blob Storage 계정에서 컨테이너를 만듭니다.

    • 원본 컨테이너. 이 컨테이너는 번역을 위해 파일을 업로드하는 위치입니다(필수).
    • 대상 컨테이너. 이 컨테이너는 번역된 파일이 저장되는 곳입니다(필수).

저장 컨테이너 권한 부여

다음 옵션 중 하나를 선택하여 번역기 리소스에 대한 액세스 권한을 부여할 수 있습니다.

✔️ 관리 ID. 관리 ID는 Azure 관리되는 리소스를 위한 Microsoft Entra ID와 특정 권한을 만드는 서비스 주체입니다. 관리 ID를 사용하면 코드에 자격 증명을 포함하지 않고도 번역기 애플리케이션을 실행할 수 있습니다. 관리 ID는 스토리지 데이터에 대한 액세스 권한을 부여하고 SAS(공유 액세스 서명 토큰)를 원본 및 대상 URL에 포함해야 하는 요구 사항을 바꾸는 더 안전한 방법입니다.

자세한 내용은 문서 번역용 관리 ID를 참조하세요.

관리 ID 흐름(RBAC)의 스크린샷.

✔️ SAS(공유 액세스 서명). 공유 액세스 서명은 번역기 서비스에 대해 지정된 기간 동안 제한된 액세스 권한을 부여하는 URL입니다. 이 방법을 사용하려면 원본 및 대상 컨테이너에 대한 SAS(공유 액세스 서명) 토큰을 만들어야 합니다. sourceUrl 및 targetUrl에는 쿼리 문자열로 추가된 SAS(공유 액세스 서명) 토큰이 포함되어야 합니다. 토큰은 컨테이너 또는 특정 Blob에 할당될 수 있습니다.

  • 원본 컨테이너 또는 Blob에는 읽기 및 나열 액세스가 지정되어 있어야 합니다.
  • 대상 컨테이너 또는 Blob에는 쓰기 및 나열 액세스가 지정되어 있어야 합니다.

자세한 내용은 SAS 토큰 만들기를 참조하세요.

SAS 토큰이 포함된 리소스 URI의 스크린샷.

애플리케이션 빌드

번역기 C#/.NET 애플리케이션을 만들기, 빌드 및 실행하는 데 사용할 수 있는 여러 도구가 있습니다. 여기에서는 CLI(명령줄 인터페이스) 또는 Visual Studio를 사용하는 방법을 안내합니다. 시작하려면 다음 탭 중 하나를 선택합니다.

프로젝트 설정

콘솔 창(예: cmd, PowerShell 또는 Bash)에서 dotnet new 명령을 사용하여 batch-document-translation라는 새 콘솔 앱을 만듭니다. 이 명령은 Program.cs라는 원본 파일 하나만 들어 있는 간단한 "Hello World" C# 프로젝트를 만듭니다.

dotnet new console -n batch-document-translation

새로 만든 앱 폴더로 디렉터리를 변경합니다. 다음 명령을 사용하여 애플리케이션을 빌드합니다.

dotnet build

빌드 출력에 경고나 오류가 포함되지 않아야 합니다.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

클라이언트 라이브러리 설치

애플리케이션 디렉터리 내에 .NET용 문서 번역 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.AI.Translation.Document --version 2.0.0-beta

문서를 비동기식으로 번역

  1. 이 프로젝트의 경우 원본 컨테이너에 업로드된 원본 문서가 필요합니다. 이 빠른 시작을 위해 문서 번역 샘플 문서를 다운로드할 수 있습니다. 소스 언어는 영어입니다.

  2. 선호하는 편집기 또는 IDE에서 프로젝트 디렉터리의 Program.cs 파일을 엽니다. Console.WriteLine("Hello World!") 줄을 포함하여 기존 코드를 삭제합니다.

  3. 애플리케이션의 Program.cs에서 키와 사용자 지정 엔드포인트에 대한 변수를 만듭니다. 자세한 내용은 키 및 사용자 지정 도메인 엔드포인트 검색을 참조하세요.

    private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

  4. 단일 Blob 컨테이너에 있는 하나 이상의 문서에 대한 번역 작업을 시작하려면 StartTranslationAsync 메서드를 호출합니다.

  5. StartTranslationAsync를 호출하려면 sourceUri, targetUri 및 targetLanguageCode 매개 변수가 포함된 DocumentTranslationInput 개체를 초기화해야 합니다.

    • 관리 ID 권한 부여의 경우 다음 변수를 만듭니다.

      • sourceUri. 번역할 문서가 포함된 원본 컨테이너의 URL입니다.

      • targetUri 번역된 문서가 기록되는 대상 컨테이너의 URL입니다.

      • targetLanguageCode. 번역된 문서의 언어 코드입니다. 언어 코드는 언어 지원 페이지에서 확인할 수 있습니다.

        원본 및 대상 URL을 찾으려면 Azure Portal에서 스토리지 계정으로 이동합니다. 왼쪽 사이드바의 데이터 스토리지에서 컨테이너를 선택하고 다음 단계에 따라 원본 문서와 대상 컨테이너 URLS를 검색합니다.

        원본 대상
        1. 원본 컨테이너 옆의 확인란을 선택합니다. 1. 대상 컨테이너 옆의 확인란을 선택합니다.
        2. 주 창 영역에서 번역할 파일이나 문서를 선택합니다. 2. 오른쪽에 있는 타원을 선택한 다음 속성을 선택합니다.
        3. 원본 URL은 속성 목록 상단에 있습니다. 3. 대상 URL은 속성 목록 상단에 있습니다.

    • SAS(공유 액세스 서명) 권한 부여를 위해 다음 변수를 만듭니다.

      • sourceUri. 번역할 문서가 포함된 원본 컨테이너에 대한 SAS 토큰이 쿼리 문자열로 추가된 SAS URI입니다.
      • targetUri 번역된 문서가 기록되는 대상 컨테이너에 대한 SAS 토큰이 쿼리 문자열로 추가된 SAS URI입니다.
      • targetLanguageCode. 번역된 문서의 언어 코드입니다. 언어 코드는 언어 지원 페이지에서 확인할 수 있습니다.

Important

완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안을 참조하세요.

비동기 번역 코드 샘플

애플리케이션의 Program.cs 파일에 다음 코드 샘플을 입력합니다.


using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

애플리케이션 실행

애플리케이션에 코드 샘플을 추가한 후 터미널에 다음 명령을 입력하여 프로젝트 디렉터리에서 애플리케이션을 실행합니다.

  dotnet run

다음은 예상 출력의 코드 조각입니다.

터미널 창의 Visual Studio Code 출력 스크린샷.

동기 번역 코드 샘플

이 빠른 시작을 위해 문서 번역 샘플 문서를 다운로드할 수 있습니다. 소스 언어는 영어입니다.



using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  string endpoint = "{your-document-translation-endpoint}";
  string apiKey = "{your-api-key}";
  SingleDocumentTranslationClient client = new SingleDocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

  try
  {
    string filePath = @"C:\{folder}\document.txt"
    using Stream fileStream = File.OpenRead(filePath);

    // MultipartFormFileData (string name, System.IO.Stream content, string contentType);
    var sourceDocument = new MultipartFormFileData(Path.GetFileName(filePath), fileStream, "application/vnd.openxmlformats-officedocument.wordprocessingml.document");

    DocumentTranslateContent content = new DocumentTranslateContent(sourceDocument);

    // DocumentTranslate (string targetLanguage, Azure.AI.Translation.Document.DocumentTranslateContent documentTranslateContent, string sourceLanguage = default, string category = default, bool? allowFallback = default, System.Threading.CancellationToken cancellationToken = default);
    var response = client.DocumentTranslate("de", content);

    Console.WriteLine($"Request string for translation: {requestString}");
    Console.WriteLine($"Response string after translation: {responseString}");
  }
    catch (RequestFailedException exception) {
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
  }
}

정말 간단하죠. .NET 클라이언트 라이브러리를 사용하여 스토리지 컨테이너에서 문서를 번역하는 프로그램을 만들었습니다.

프로젝트 설정

최신 버전의 Python이 설치되어 있는지 확인합니다.

클라이언트 라이브러리 설치

최신 버전의 문서 번역 클라이언트 라이브러리를 설치합니다.

  pip install azure-ai-translation-document==1.1.0b1

배치 파일 번역

  1. 이 프로젝트의 경우 원본 컨테이너에 업로드된 원본 문서가 필요합니다. 이 빠른 시작을 위해 문서 번역 샘플 문서를 다운로드할 수 있습니다. 소스 언어는 영어입니다.

  2. Python 애플리케이션 파일에서 리소스 키와 사용자 지정 엔드포인트에 대한 변수를 만듭니다. 자세한 내용은 키 및 사용자 지정 도메인 엔드포인트 검색을 참조하세요.

key = "{your-api-key}"
endpoint = "{your-document-translation-endpoint}"

  1. endpoint 및 key 매개 변수가 포함된 DocumentTranslationClient 개체를 초기화합니다.

  2. begin_translation 메서드를 호출하고 sourceUri, targetUri 및 targetLanguageCode 매개 변수를 전달합니다.

    • 관리 ID 권한 부여의 경우 다음 변수를 만듭니다.

      • sourceUri. 번역할 문서가 포함된 원본 컨테이너의 URL입니다.

      • targetUri 번역된 문서가 기록되는 대상 컨테이너의 URL입니다.

      • targetLanguageCode. 번역된 문서의 언어 코드입니다. 언어 코드는 언어 지원 페이지에서 확인할 수 있습니다.

        원본 및 대상 URL을 찾으려면 Azure Portal에서 스토리지 계정으로 이동합니다. 왼쪽 사이드바의 데이터 스토리지에서 컨테이너를 선택하고 다음 단계에 따라 원본 문서와 대상 컨테이너 URLS를 검색합니다.

        원본 대상
        1. 원본 컨테이너 옆의 확인란을 선택합니다. 1. 대상 컨테이너 옆의 확인란을 선택합니다.
        2. 주 창 영역에서 번역할 파일이나 문서를 선택합니다. 2. 오른쪽에 있는 타원을 선택한 다음 속성을 선택합니다.
        3. 원본 URL은 속성 목록 상단에 있습니다. 3. 대상 URL은 속성 목록 상단에 있습니다.

    • SAS(공유 액세스 서명) 권한 부여를 위해 다음 변수를 만듭니다.

      • sourceUri. 번역할 문서가 포함된 원본 컨테이너에 대한 SAS 토큰이 쿼리 문자열로 추가된 SAS URI입니다.
      • targetUri 번역된 문서가 기록되는 대상 컨테이너에 대한 SAS 토큰이 쿼리 문자열로 추가된 SAS URI입니다.
      • targetLanguageCode. 번역된 문서의 언어 코드입니다. 언어 코드는 언어 지원 페이지에서 확인할 수 있습니다.

비동기 번역 코드 샘플

Important

완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure AI 서비스 보안을 참조하세요.

Python 애플리케이션에 다음 코드 샘플을 입력합니다.


#  import libraries
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = '{your-api-key}'
endpoint = '{your-document-translation-endpoint}'
sourceUri = '<your-container-sourceUrl>'
targetUri = '<your-container-targetUrl>'
targetLanguage = '<target-language-code>'


# initialize a new instance of the DocumentTranslationClient object to interact with the asynchronous Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

print('Status: {}'.format(poller.status()))
print('Created on: {}'.format(poller.details.created_on))
print('Last updated on: {}'.format(poller.details.last_updated_on))
print(
    'Total number of translations on documents: {}'.format(
        poller.details.documents_total_count
    )
)

print('\nOf total documents...')
print('{} failed'.format(poller.details.documents_failed_count))
print('{} succeeded'.format(poller.details.documents_succeeded_count))

for document in result:
    print('Document ID: {}'.format(document.id))
    print('Document status: {}'.format(document.status))
    if document.status == 'Succeeded':
        print('Source document location: {}'.format(document.source_document_url))
        print(
            'Translated document location: {}'.format(document.translated_document_url)
        )
        print('Translated to language: {}\n'.format(document.translated_to))
    else:
        print(
            'Error Code: {}, Message: {}\n'.format(
                document.error.code, document.error.message
            )
        )

애플리케이션 실행

애플리케이션에 코드 샘플을 추가한 후 터미널에 다음 명령을 입력합니다.

python asynchronous-sdk.py

다음은 예상 출력의 코드 조각입니다.

터미널 창의 Python 출력 스크린샷.

동기 번역 코드 샘플

이 빠른 시작을 위해 문서 번역 샘플 문서를 다운로드할 수 있습니다. 소스 언어는 영어입니다.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.ai.translation.document.models import DocumentTranslateContent


def sample_single_document_translation():

    # create variables for your resource api key, document translation endpoint, and target language
    key = "<your-api-key>"
    endpoint = "<your-document-translation-endpoint>"
    target_language = "{target-language-code}"

    # initialize a new instance of the SingleDocumentTranslationClient object to interact with the synchronous Document Translation feature
    client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))

    # absolute path to your document
    file_path = "C:/{your-file-path}/document-translation-sample.docx"
    file_name = os.path.path.basename(file_path)
    file_type = (
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
    print(f"File for translation: {file_name}")

    with open(file_name, "r") as file:
        file_contents = file.read()

    document_content = (file_name, file_contents, file_type)
    document_translate_content = DocumentTranslateContent(document=document_content)

    response_stream = client.document_translate(
        body=document_translate_content, target_language=target_language
    )
    translated_response = response_stream.decode("utf-8-sig")  # type: ignore[attr-defined]
    print(f"Translated response: {translated_response}")


if __name__ == "__main__":
    sample_single_document_translation()

정말 간단하죠. Python 클라이언트 라이브러리를 사용하여 비동기식 및 동기식으로 문서를 번역하는 프로그램을 만들었습니다.

다음 단계

문서 번역 작업에 대해 자세히 알아보기