Udostępnij za pośrednictwem

Wprowadzenie: biblioteki klienta tłumaczenia dokumentów

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 jednoczesnym zachowaniu struktury i formatowania tekstu.

Ważne

  • Tłumaczenie dokumentów jest obecnie obsługiwane tylko w zasobie usługi Azure AI 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. Language Studio obsługuje warstwy wystąpień S1 lub D3. Zalecamy wybranie Standard S1, aby wypróbować tłumaczenie dokumentu. ZobaczCennik 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 wydaniem ogólnie dostępnej wersji 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:

Autoryzacja kontenera magazynowego

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

✔️ Zarządzane tożsamości. 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 Azure AI Translator bez potrzeby umieszczania 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, zobaczToż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 twojego kontenera lub do konkretnych obiektów blob.

  • Źródłowy kontener lub obiekt blob musi mieć wyznaczony dostęp do odczytu i dostęp do 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 zakładek, aby rozpocząć.

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. Aby rozpocząć szybko, możesz pobrać nasz przykładowy dokument tłumaczenia. 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, zobaczPobieranie 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 w celu rozpoczęcia operacji tłumaczenia dla jednego lub więcej dokumentów w pojedynczym kontenerze obiektów blob.

  5. Aby wywołać StartTranslationAsync, należy zainicjować obiekt DocumentTranslationInput zawierający parametry sourceUri, targetUri i targetLanguageCode.

    • W celu autoryzacji Managed Identity 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 magazynowania w portalu Azure. 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.

        Źródło Cel
        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 SAS z dołączonym tokenem SAS jako ciągiem zapytania dla źródłowego kontenera zawierającego dokumenty do przetłumaczenia.
      • targetUri Identyfikator URI SAS z dołączonym tokenem SAS jako część 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 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 wyniku:

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

Przykładowy kod translacji synchronicznej

Aby rozpocząć szybko, możesz pobrać nasz przykładowy dokument tłumaczenia. 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 stworzyłeś program do tłumaczenia dokumentów w kontenerze za pomocą biblioteki klienta .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.0.0

Tłumaczenie plików wsadowych

  1. W tym projekcie potrzebny jest dokument źródłowy przekazany do kontenera źródłowego. Aby rozpocząć szybko, możesz pobrać nasz przykładowy dokument tłumaczenia. 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, zobaczPobieranie klucza i niestandardowego punktu końcowego domeny.

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

  1. Zainicjuj obiekt DocumentTranslationClient, który zawiera parametry endpoint i key.

  2. Wywołaj metodę begin_translation i przekaż parametry sourceUri, targetUri i targetLanguageCode.

    • W celu autoryzacji Managed Identity 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 magazynowania w portalu Azure. 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.

        Źródło Cel
        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 SAS z dołączonym tokenem SAS jako ciągiem zapytania dla źródłowego kontenera zawierającego dokumenty do przetłumaczenia.
      • targetUri Identyfikator URI SAS z dołączonym tokenem SAS jako część 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 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 wyniku:

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

Przykładowy kod translacji synchronicznej

Aby rozpocząć szybko, możesz pobrać nasz przykładowy dokument tłumaczenia. 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.basename(file_path)
    file_type = (
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
    print(f"File for translation: {file_name}")

    with open(file_path, "rb") 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
    )
    # Save the response_stream to a file
    output_file_path = "./translated-document.docx"
    with open(output_file_path, "wb") as output_file:
        output_file.write(response_stream)
    
    print(f"Translated document saved to: {output_file_path}")


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