Sdílet prostřednictvím

Začínáme: Klientské knihovny pro překlad dokumentů

  • Článek

Překlad dokumentů je cloudová funkce služby Azure AI Translator, která asynchronně překládá celé dokumenty v podporovaných jazycích a různých formátech souborů. V tomto rychlém startu se naučíte používat překlad dokumentů s programovacím jazykem podle vašeho výběru k překladu zdrojového dokumentu do cílového jazyka při zachování struktury a formátování textu.

Důležité

  • Překlad dokumentů se v současné době podporuje jenom v prostředku služby Translator (jedna služba) a není součástí prostředku služeb Azure AI (více služeb).
  • Překlad dokumentů je podporován na placených úrovních. Language Studio podporuje úrovně instancí S1 nebo D3. Doporučujeme vybrat standardní S1 a vyzkoušet překlad dokumentu. Podívejte se na ceny služeb Azure AI – Translator.
  • Verze Public Preview pro překlad dokumentů poskytují dřívější přístup k funkcím, které jsou v aktivním vývoji. Funkce, přístupy a procesy se můžou před obecnou dostupností (GA) změnit na základě zpětné vazby uživatelů.
  • Verze Public Preview klientských knihoven překladu dokumentů ve výchozím nastavení je rest API verze 2024-05-01.

Požadavky

Na začátek budete potřebovat:

  • Aktivní účet Azure Pokud žádné nemáte, můžete si vytvořit bezplatný účet.

  • Prostředek Translator s jednou službou (nikoli prostředek služeb Azure AI s více službami). Pokud plánujete používat funkci Překlad dokumentů s autorizací spravované identity, zvolte geografickou oblast, například USA – východ. Vyberte plán služby Standard S1 Standard (průběžné platby) nebo C2, C3, C4 nebo D3 Volume Discount Plans.

  • Účet služby Azure Blob Storage. Kontejnery vytvoříte v účtu služby Azure Blob Storage pro zdrojové a cílové soubory:

    • Zdrojový kontejner. V tomto kontejneru nahrajete soubory pro překlad (povinné).
    • Cílový kontejner. V tomto kontejneru jsou uložené přeložené soubory (povinné).

Autorizace kontejneru úložiště

Pokud chcete autorizovat přístup k prostředku Služby Translator, můžete zvolit jednu z následujících možností.

✔️ Spravovaná identita Spravovaná identita je instanční objekt, který vytvoří identitu Microsoft Entra a konkrétní oprávnění pro spravovaný prostředek Azure. Spravované identity umožňují spouštět aplikaci Translator, aniž byste museli vkládat přihlašovací údaje do kódu. Spravované identity představují bezpečnější způsob, jak udělit přístup k datům úložiště a nahradit požadavek na zahrnutí tokenů sdíleného přístupového podpisu (SAS) ke zdroji a cílovým adresám URL.

Další informace najdete v tématu Spravované identity pro překlad dokumentů.

Snímek obrazovky s tokem spravované identity (RBAC).

✔️ Sdílený přístupový podpis (SAS) Sdílený přístupový podpis je adresa URL, která uděluje omezený přístup po určitou dobu službě Translator. Pokud chcete použít tuto metodu, musíte pro zdrojové a cílové kontejnery vytvořit tokeny sdíleného přístupového podpisu (SAS). targetUrl Token sourceUrl sdíleného přístupového podpisu (SAS) musí obsahovat připojený jako řetězec dotazu. Token se dá přiřadit ke kontejneru nebo konkrétním objektům blob.

  • Zdrojový kontejner nebo objekt blob musí určit přístup pro čtení a seznam.
  • Cílový kontejner nebo objekt blob musí určit přístup k zápisu a seznamu.

Další informace najdete v tématu Vytváření tokenů SAS.

Snímek obrazovky s identifikátorem URI prostředku s tokenem SAS

Sestavení aplikace

K dispozici je několik nástrojů pro vytváření, sestavování a spouštění aplikací Translator C#/.NET. Tady vás provedeme pomocí rozhraní příkazového řádku (CLI) nebo sady Visual Studio. Začněte výběrem jedné z následujících karet:

Nastavení projektu

V okně konzoly (například cmd, PowerShell nebo Bash) pomocí dotnet new příkazu vytvořte novou konzolovou aplikaci s názvem batch-document-translation. Tento příkaz vytvoří jednoduchý projekt "Hello World" C# s jedním zdrojovým souborem: Program.cs.

dotnet new console -n batch-document-translation

Změňte adresář na nově vytvořenou složku aplikace. Sestavte aplikaci pomocí následujícího příkazu:

dotnet build

Výstup sestavení by neměl obsahovat žádná upozornění ani chyby.

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

Instalace klientské knihovny

V adresáři aplikace nainstalujte klientskou knihovnu pro překlad dokumentů pro .NET:

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

Asynchronní překlad dokumentů

  1. Pro tento projekt potřebujete zdrojový dokument nahraný do zdrojového kontejneru. Pro účely tohoto rychlého startu si můžete stáhnout ukázkový dokument překladu dokumentů. Zdrojový jazyk je angličtina.

  2. V adresáři projektu otevřete soubor Program.cs v preferovaném editoru nebo integrovaném vývojovém prostředí (IDE). Odstraňte existující kód včetně řádku Console.WriteLine("Hello World!").

  3. V Program.cs aplikace vytvořte proměnné pro klíč a vlastní koncový bod. Další informace najdete v tématu Načtení klíče a vlastního koncového bodu domény.

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

  4. StartTranslationAsync Voláním metody spusťte operaci překladu pro jeden nebo více dokumentů v jednom kontejneru objektů blob.

  5. Chcete-li volat StartTranslationAsync, musíte inicializovat DocumentTranslationInput objekt, který obsahuje sourceUri, targetUria targetLanguageCode parametry:

    • Pro autorizaci spravované identity vytvořte tyto proměnné:

      • sourceUri. Adresa URL zdrojového kontejneru obsahujícího dokumenty, které se mají přeložit.

      • targetUri Adresa URL cílového kontejneru, do kterého se zapisují přeložené dokumenty.

      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

        Pokud chcete najít zdrojové a cílové adresy URL, přejděte na webu Azure Portal ke svému účtu úložiště. Na levém bočním panelu v části Úložiště dat vyberte Kontejnery a následujícím postupem načtěte zdrojové dokumenty a cílový kontejner URLS.

        Source Cíl
        1. Zaškrtněte políčko vedle zdrojového kontejneru. 1. Zaškrtněte políčko vedle cílového kontejneru.
        2. V oblasti hlavního okna vyberte soubor nebo dokumenty pro překlad. 2. Vyberte tři tečky umístěné vpravo a pak zvolte Vlastnosti.
        3. Zdrojová adresa URL se nachází v horní části seznamu Vlastností. 3. Cílová adresa URL se nachází v horní části seznamu Vlastností.

    • Pro autorizaci sdíleného přístupového podpisu (SAS) vytvořte tyto proměnné.

      • sourceUri. Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro zdrojový kontejner obsahující dokumenty, které se mají přeložit.
      • targetUri Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro cílový kontejner, do kterého se zapisují přeložené dokumenty.
      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v tématu Zabezpečení služeb Azure AI.

Ukázka kódu asynchronního překladu

Do souboru Program.cs vaší aplikace zadejte následující vzorový kód:


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

Spusťte aplikaci

Po přidání ukázky kódu do aplikace spusťte aplikaci z adresáře projektu zadáním následujícího příkazu v terminálu:

  dotnet run

Tady je fragment očekávaného výstupu:

Snímek obrazovky s výstupem editoru Visual Studio Code v okně terminálu

Ukázka synchronního kódu překladu

Pro účely tohoto rychlého startu si můžete stáhnout ukázkový dokument překladu dokumentů. Zdrojový jazyk je angličtina.



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

A je to! Právě jste vytvořili program pro překlad dokumentů v kontejneru úložiště pomocí klientské knihovny .NET.

Nastavení projektu

Ujistěte se, že je nainstalovaná nejnovější verze Pythonu.

Instalace klientské knihovny

Nainstalujte nejnovější verzi klientské knihovny překladu dokumentů:

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

Překlad dávkových souborů

  1. Pro tento projekt potřebujete zdrojový dokument nahraný do zdrojového kontejneru. Pro účely tohoto rychlého startu si můžete stáhnout ukázkový dokument překladu dokumentů. Zdrojový jazyk je angličtina.

  2. V souboru aplikace Pythonu vytvořte proměnné pro klíč prostředku a vlastní koncový bod. Další informace najdete v tématu Načtení klíče a vlastního koncového bodu domény.

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

  1. Inicializace objektu DocumentTranslationClient , který obsahuje vaše endpoint a key parametry.

  2. Zavolejte metodu begin_translation a předejte sourceUriparametr , targetUria targetLanguageCode parametry.

    • Pro autorizaci spravované identity vytvořte tyto proměnné:

      • sourceUri. Adresa URL zdrojového kontejneru obsahujícího dokumenty, které se mají přeložit.

      • targetUri Adresa URL cílového kontejneru, do kterého se zapisují přeložené dokumenty.

      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

        Pokud chcete najít zdrojové a cílové adresy URL, přejděte na webu Azure Portal ke svému účtu úložiště. Na levém bočním panelu v části Úložiště dat vyberte Kontejnery a následujícím postupem načtěte zdrojové dokumenty a cílový kontejner URLS.

        Source Cíl
        1. Zaškrtněte políčko vedle zdrojového kontejneru. 1. Zaškrtněte políčko vedle cílového kontejneru.
        2. V oblasti hlavního okna vyberte soubor nebo dokumenty pro překlad. 2. Vyberte tři tečky umístěné vpravo a pak zvolte Vlastnosti.
        3. Zdrojová adresa URL se nachází v horní části seznamu Vlastností. 3. Cílová adresa URL se nachází v horní části seznamu Vlastností.

    • Pro autorizaci sdíleného přístupového podpisu (SAS) vytvořte tyto proměnné.

      • sourceUri. Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro zdrojový kontejner obsahující dokumenty, které se mají přeložit.
      • targetUri Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro cílový kontejner, do kterého se zapisují přeložené dokumenty.
      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

Ukázka kódu asynchronního překladu

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v tématu Zabezpečení služeb Azure AI.

Do aplikace v Pythonu zadejte následující vzorový kód:


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

Spusťte aplikaci

Po přidání ukázky kódu do aplikace zadejte do terminálu následující příkaz:

python asynchronous-sdk.py

Tady je fragment očekávaného výstupu:

Snímek obrazovky s výstupem Pythonu v okně terminálu

Ukázka synchronního kódu překladu

Pro účely tohoto rychlého startu si můžete stáhnout ukázkový dokument překladu dokumentů. Zdrojový jazyk je angličtina.

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

A je to! Právě jste vytvořili program pro asynchronní a synchronní překlad dokumentů pomocí klientské knihovny Pythonu.

Další krok

Další informace o operacích překladu dokumentů