Sdílet prostřednictvím

Začínáme: Sady SDK pro překlad dokumentů pomocí služby Translator

Překlad dokumentů je cloudová funkce služby Azure 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ů je aktuálně podporován pouze v prostředku Azure Translator (jedna služba) a není součástí prostředku Foundry Tools (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 naceny za Foundry Tools – Translator.
  • Verze Public Preview pro překlad dokumentů poskytují dřívější přístup k funkcím, které jsou aktivní ve vývoji. Funkce, přístupy a procesy se můžou změnit před vydáním obecné dostupnosti (GA) na základě zpětné vazby uživatelů.
  • Verze Public Preview klientských knihoven překladu dokumentů má výchozí hodnotu rozhraní 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 Azure Translator s jednou službou (nikoli prostředek Microsoft Foundry s více službami). Pokud plánujete používat funkci překladu dokumentů s autorizací spravované identity, zvolte geografickou oblast, například USA – východ. Vyberte Standardní S1 standardní plán služeb nebo plány s objemovou slevou C2, C3, C4 nebo D3.

    • Po nasazení prostředku vyberte možnost Přejít k prostředku a získejte klíč a koncový bod.

    • K připojení aplikace k Azure Translatoru potřebujete klíč a koncový bod ze zdroje. Klíč a koncový bod vložíte do kódu později v rychlém startu. Tyto hodnoty můžete najít na stránce Klíče a koncové body Azure Portal.

      Snímek obrazovky s klíčem překladu dokumentu a umístěním koncového bodu na webu Azure Portal

  • Úč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 Azure Translator, můžete zvolit jednu z následujících možností.

✔️ Spravovaná identita Spravovaná identita je služební principál, který vytvoří identitu Microsoft Entra a konkrétní oprávnění pro spravovaný prostředek Azure. Spravované identity umožňují spustit aplikaci Azure 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ématuSpravované identity pro překlad dokumentů.

Snímek obrazovky ukazující tok spravované identity (RBAC).

✔️ Sdílený přístupový podpis (SAS) Sdílený přístupový podpis je adresa URL, která službě Translator uděluje omezený přístup po určitou dobu. 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). sourceUrl Token targetUrl sdíleného přístupového podpisu (SAS) musí obsahovat připojený jako řetězec dotazu. Token lze přiřadit vašemu kontejneru nebo specifickým blobům.

  • Zdrojový kontejner nebo objekt blob musí určit přístup ke čtení a přístup k seznamu.
  • Cílový kontejner nebo objekt blob musí mít určeno přístup k zápisu a přístup k výpisu.

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

Snímek obrazovky identifikátoru URI prostředku se SAS tokenem.

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 zahájení si můžete stáhnout ukázkový dokument pro překlad 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 váš klíč a vlastní koncový bod. Další informace najdete v tématuJak získat svůj klíč a vlastní koncový bod domény.

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

  4. Voláním metody StartTranslationAsync spusťte operaci překladu pro jeden nebo více dokumentů v jednom kontejneru 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.

        Zdroj 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 ikonu tří teček umístěnou 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 viz Zabezpečení nástrojů Foundry .

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 zahájení si můžete stáhnout ukázkový dokument pro překlad 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 pro překlad dokumentů:

  pip install azure-ai-translation-document==1.0.0

Překlad dávkových souborů

  1. Pro tento projekt potřebujete zdrojový dokument nahraný do zdrojového kontejneru. Pro účely tohoto rychlého zahájení si můžete stáhnout ukázkový dokument pro překlad 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ématuJak získat svůj klíč a vlastní koncový bod 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 parametry sourceUri, targetUri a targetLanguageCode.

    • 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.

        Zdroj 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 ikonu tří teček umístěnou 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 viz Zabezpečení nástrojů Foundry .

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 zahájení si můžete stáhnout ukázkový dokument pro překlad 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.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()

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ů

  • Last updated on