Udostępnij za pośrednictwem

Wprowadzenie: biblioteki klienckie tłumaczenia dokumentów

  • Artykuł

Tłumaczenie dokumentów to funkcja oparta na chmurze usługi Azure AI Translator , która asynchronicznie tłumaczy całe dokumenty w obsługiwanych językach i różnych formatach plików. W tym przewodniku Szybki start dowiesz się, jak używać tłumaczenia dokumentów z wybranym językiem programowania, aby przetłumaczyć dokument źródłowy na język docelowy przy zachowaniu struktury i formatowania tekstu.

Ważne

  • Tłumaczenie dokumentów jest obecnie obsługiwane tylko w zasobie translator (pojedynczej usługi) i nie jest uwzględniane w zasobie usług Azure AI (multi-service).
  • Tłumaczenie dokumentów jest obsługiwane w warstwach płatnych. Program Language Studio obsługuje warstwy wystąpień S1 lub D3. Zalecamy wybranie warstwy Standardowa S1 w celu wypróbowania tłumaczenia dokumentów. Zobacz Cennik usług Azure AI — Translator.
  • Publiczne wersje zapoznawcze tłumaczenia dokumentów zapewniają wczesny dostęp do funkcji, które są aktywnie opracowywane. Funkcje, podejścia i procesy mogą ulec zmianie przed ogólną dostępnością na podstawie opinii użytkowników.
  • Publiczna wersja zapoznawcza bibliotek klienckich tłumaczenia dokumentów jest domyślna dla interfejsu API REST w wersji 2024-05-01.

Wymagania wstępne

Aby rozpocząć pracę, potrzebne będą następujące elementy:

  • Aktywne konto platformy Azure. Jeśli nie masz, możesz utworzyć bezpłatne konto.

  • Zasób usługi Translator z jedną usługą (nie zasób wielosługowych usług Azure AI). Jeśli planujesz korzystanie z funkcji tłumaczenia dokumentów z autoryzacją tożsamości zarządzanej, wybierz region geograficzny, taki jak Wschodnie stany USA. Wybierz plan usługi Standardowa S1 (płatność zgodnie z rzeczywistym użyciem) lub C2, C3, C4 lub D3 — plany rabatów zbiorczych.

  • Konto usługi Azure Blob Storage. Kontenery utworzysz na koncie usługi Azure Blob Storage dla plików źródłowych i docelowych:

    • Kontener źródłowy. Ten kontener służy do przekazywania plików do tłumaczenia (wymagane).
    • Kontener docelowy. W tym kontenerze przechowywane są przetłumaczone pliki (wymagane).

Autoryzacja kontenera magazynu

Możesz wybrać jedną z następujących opcji, aby autoryzować dostęp do zasobu usługi Translator.

✔️ Tożsamość zarządzana. Tożsamość zarządzana to jednostka usługi, która tworzy tożsamość firmy Microsoft Entra i określone uprawnienia dla zasobu zarządzanego platformy Azure. Tożsamości zarządzane umożliwiają uruchamianie aplikacji translator bez konieczności osadzania poświadczeń w kodzie. Tożsamości zarządzane to bezpieczniejszy sposób udzielania dostępu do danych magazynu i zastępowania wymagań dotyczących dołączania tokenów sygnatury dostępu współdzielonego (SAS) do źródłowych i docelowych adresów URL.

Aby dowiedzieć się więcej, zobacz Tożsamości zarządzane na potrzeby tłumaczenia dokumentów.

Zrzut ekranu przedstawiający przepływ tożsamości zarządzanej (RBAC).

✔️ Sygnatura dostępu współdzielonego (SAS). Sygnatura dostępu współdzielonego to adres URL, który udziela ograniczonego dostępu przez określony okres do usługi Translator. Aby użyć tej metody, należy utworzyć tokeny sygnatury dostępu współdzielonego (SAS) dla kontenerów źródłowych i docelowych. Element sourceUrl i targetUrl musi zawierać token sygnatury dostępu współdzielonego (SAS) dołączony jako ciąg zapytania. Token można przypisać do kontenera lub określonych obiektów blob.

  • Źródłowy kontener lub obiekt blob musi wyznaczyć dostęp do odczytu i listy.
  • Docelowy kontener lub obiekt blob musi wyznaczyć dostęp do zapisu i listy.

Aby dowiedzieć się więcej, zobacz Tworzenie tokenów SAS.

Zrzut ekranu przedstawiający identyfikator URI zasobu z tokenem SAS.

Kompilowanie aplikacji

Dostępnych jest kilka narzędzi do tworzenia, kompilowania i uruchamiania aplikacji Translator C#/.NET. W tym miejscu przeprowadzimy Cię przez proces korzystania z interfejsu wiersza polecenia lub programu Visual Studio. Wybierz jedną z następujących kart, aby rozpocząć pracę:

konfigurowanie projektu

W oknie konsoli (takim jak cmd, PowerShell lub Bash) użyj dotnet new polecenia , aby utworzyć nową aplikację konsolową o nazwie batch-document-translation. To polecenie tworzy prosty projekt języka C# "Hello World" z jednym plikiem źródłowym: Program.cs.

dotnet new console -n batch-document-translation

Zmień katalog na nowo utworzony folder aplikacji. Skompiluj aplikację za pomocą następującego polecenia:

dotnet build

Dane wyjściowe kompilacji nie powinny zawierać żadnych ostrzeżeń ani błędów.

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

Instalowanie biblioteki klienta

W katalogu aplikacji zainstaluj bibliotekę klienta tłumaczenia dokumentów dla platformy .NET:

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

Asynchroniczne tłumaczenie dokumentów

  1. W tym projekcie potrzebny jest dokument źródłowy przekazany do kontenera źródłowego. Na potrzeby tego przewodnika Szybki start możesz pobrać nasz przykładowy dokument tłumaczenia dokumentów. Język źródłowy to angielski.

  2. W katalogu projektu otwórz plik Program.cs w preferowanym edytorze lub środowisku IDE. Usuń istniejący kod, w tym wiersz Console.WriteLine("Hello World!").

  3. W Program.cs aplikacji utwórz zmienne dla klucza i niestandardowego punktu końcowego. Aby uzyskać więcej informacji, zobacz Pobieranie klucza i niestandardowego punktu końcowego domeny.

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

  4. Wywołaj metodę , StartTranslationAsync aby uruchomić operację tłumaczenia dla co najmniej jednego dokumentu w jednym kontenerze obiektów blob.

  5. Aby wywołać StartTranslationAsyncmetodę DocumentTranslationInput , należy zainicjować obiekt zawierający sourceUriparametry , targetUrii targetLanguageCode :

    • W przypadku autoryzacji tożsamości zarządzanej utwórz następujące zmienne:

      • sourceUri. Adres URL kontenera źródłowego zawierającego dokumenty do tłumaczenia.

      • targetUri Adres URL kontenera docelowego, do którego zapisywane są przetłumaczone dokumenty.

      • targetLanguageCode. Kod języka przetłumaczonych dokumentów. Kody języków można znaleźć na naszej stronie pomocy technicznej dotyczącej języka.

        Aby znaleźć źródłowe i docelowe adresy URL, przejdź do konta magazynu w witrynie Azure Portal. Na pasku bocznym po lewej stronie w obszarze Magazyn danych wybierz pozycję Kontenery i wykonaj następujące kroki, aby pobrać dokumenty źródłowe i kontener docelowy URLS.

        Lokalizacja źródłowa Target
        1. Zaznacz pole wyboru obok kontenera źródłowego 1. Zaznacz pole wyboru obok kontenera docelowego.
        2. W obszarze głównym okna wybierz plik lub dokumenty do tłumaczenia. 2. Wybierz wielokropek znajdujący się po prawej stronie, a następnie wybierz pozycję Właściwości.
        3. Źródłowy adres URL znajduje się w górnej części listy Właściwości. 3. Docelowy adres URL znajduje się w górnej części listy Właściwości.

    • W przypadku autoryzacji sygnatury dostępu współdzielonego (SAS) utwórz te zmienne

      • sourceUri. Identyfikator URI sygnatury dostępu współdzielonego z tokenem SAS dołączonym jako ciąg zapytania dla kontenera źródłowego zawierającego dokumenty do tłumaczenia.
      • targetUri Identyfikator URI sygnatury dostępu współdzielonego z tokenem SAS dołączonym jako ciąg zapytania dla kontenera docelowego, do którego zapisywane są przetłumaczone dokumenty.
      • targetLanguageCode. Kod języka przetłumaczonych dokumentów. Kody języków można znaleźć na naszej stronie pomocy technicznej dotyczącej języka.

Ważne

Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz Zabezpieczenia usług Azure AI.

Przykładowy kod translacji asynchronicznej

Wprowadź następujący przykładowy kod w pliku Program.cs aplikacji:


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

Uruchamianie aplikacji

Po dodaniu przykładowego kodu do aplikacji uruchom aplikację z katalogu projektu, wpisując następujące polecenie w terminalu:

  dotnet run

Oto fragment oczekiwanego danych wyjściowych:

Zrzut ekranu przedstawiający dane wyjściowe programu Visual Studio Code w oknie terminalu.

Przykładowy kod translacji synchronicznej

Na potrzeby tego przewodnika Szybki start możesz pobrać nasz przykładowy dokument tłumaczenia dokumentów. Język źródłowy to angielski.



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

I już! Właśnie utworzono program do tłumaczenia dokumentów w kontenerze magazynu przy użyciu biblioteki klienta platformy .NET.

konfigurowanie projektu

Upewnij się, że zainstalowano najnowszą wersję języka Python .

Instalowanie biblioteki klienta

Zainstaluj najnowszą wersję biblioteki klienta tłumaczenia dokumentów:

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

Tłumaczenie plików wsadowych

  1. W tym projekcie potrzebny jest dokument źródłowy przekazany do kontenera źródłowego. Na potrzeby tego przewodnika Szybki start możesz pobrać nasz przykładowy dokument tłumaczenia dokumentów. Język źródłowy to angielski.

  2. W pliku aplikacji języka Python utwórz zmienne dla klucza zasobu i niestandardowego punktu końcowego. Aby uzyskać więcej informacji, zobacz Pobieranie klucza i niestandardowego punktu końcowego domeny.

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

  1. Zainicjuj DocumentTranslationClient obiekt zawierający endpoint parametry i .key

  2. Wywołaj metodę begin_translation i przekaż sourceUriparametry , targetUrii targetLanguageCode .

    • W przypadku autoryzacji tożsamości zarządzanej utwórz następujące zmienne:

      • sourceUri. Adres URL kontenera źródłowego zawierającego dokumenty do tłumaczenia.

      • targetUri Adres URL kontenera docelowego, do którego zapisywane są przetłumaczone dokumenty.

      • targetLanguageCode. Kod języka przetłumaczonych dokumentów. Kody języków można znaleźć na naszej stronie pomocy technicznej dotyczącej języka.

        Aby znaleźć źródłowe i docelowe adresy URL, przejdź do konta magazynu w witrynie Azure Portal. Na pasku bocznym po lewej stronie w obszarze Magazyn danych wybierz pozycję Kontenery i wykonaj następujące kroki, aby pobrać dokumenty źródłowe i kontener docelowy URLS.

        Lokalizacja źródłowa Target
        1. Zaznacz pole wyboru obok kontenera źródłowego 1. Zaznacz pole wyboru obok kontenera docelowego.
        2. W obszarze głównym okna wybierz plik lub dokumenty do tłumaczenia. 2. Wybierz wielokropek znajdujący się po prawej stronie, a następnie wybierz pozycję Właściwości.
        3. Źródłowy adres URL znajduje się w górnej części listy Właściwości. 3. Docelowy adres URL znajduje się w górnej części listy Właściwości.

    • W przypadku autoryzacji sygnatury dostępu współdzielonego (SAS) utwórz te zmienne

      • sourceUri. Identyfikator URI sygnatury dostępu współdzielonego z tokenem SAS dołączonym jako ciąg zapytania dla kontenera źródłowego zawierającego dokumenty do tłumaczenia.
      • targetUri Identyfikator URI sygnatury dostępu współdzielonego z tokenem SAS dołączonym jako ciąg zapytania dla kontenera docelowego, do którego zapisywane są przetłumaczone dokumenty.
      • targetLanguageCode. Kod języka przetłumaczonych dokumentów. Kody języków można znaleźć na naszej stronie pomocy technicznej dotyczącej języka.

Przykładowy kod translacji asynchronicznej

Ważne

Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz Zabezpieczenia usług Azure AI.

Wprowadź następujący przykładowy kod w aplikacji w języku 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
            )
        )

Uruchamianie aplikacji

Po dodaniu przykładowego kodu do aplikacji wpisz następujące polecenie w terminalu:

python asynchronous-sdk.py

Oto fragment oczekiwanego danych wyjściowych:

Zrzut ekranu przedstawiający dane wyjściowe języka Python w oknie terminalu.

Przykładowy kod translacji synchronicznej

Na potrzeby tego przewodnika Szybki start możesz pobrać nasz przykładowy dokument tłumaczenia dokumentów. Język źródłowy to angielski.

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

I już! Właśnie utworzono program do translacji dokumentów asynchronicznie i synchronicznie przy użyciu biblioteki klienta języka Python.

Następny krok

Dowiedz się więcej o operacjach tłumaczenia dokumentów