Dela via

Kom igång: Klientbibliotek för dokumentöversättning

  • Artikel

Dokumentöversättning är en molnbaserad funktion i Azure AI Translator-tjänsten som asynkront översätter hela dokument på språk som stöds och olika filformat. I den här snabbstarten lär du dig att använda dokumentöversättning med valfritt programmeringsspråk för att översätta ett källdokument till ett målspråk samtidigt som du bevarar struktur och textformatering.

Viktigt!

  • Dokumentöversättning stöds för närvarande endast i Translator-resursen (enskild tjänst) och ingår inte i Azure AI-tjänsternas resurs (flera tjänster).
  • Dokumentöversättning stöds på betalda nivåer. Language Studio stöder instansnivåerna S1 eller D3. Vi föreslår att du väljer Standard S1 för att prova dokumentöversättning. Se Prissättning för Azure AI-tjänster – Translator.
  • Offentliga förhandsversioner av dokumentöversättning ger tidig åtkomst till funktioner som är i aktiv utveckling. Funktioner, metoder och processer kan ändras, före allmän tillgänglighet (GA), baserat på användarfeedback.
  • Den offentliga förhandsversionen av klientbibliotek för dokumentöversättning är som standard REST API version 2024-05-01.

Förutsättningar

Du behöver följande för att komma igång:

  • Ett aktivt Azure-konto. Om du inte har någon, kan du skapa ett kostnadsfritt konto.

  • En Translator-resurs med en enda tjänst (inte en Azure AI-tjänstresurs med flera tjänster). Om du planerar att använda funktionen Dokumentöversättning med hanterad identitetsauktorisering väljer du en geografisk region som USA, östra. Välj Standard S1 Standard Service Plan (Betala per användning) eller C2, C3, C4 eller D3 Volymrabattplaner.

  • Ett Azure Blob Storage-konto. Du skapar containrar i ditt Azure Blob Storage-konto för dina käll- och målfiler:

    • Källcontainer. I den här containern laddar du upp dina filer för översättning (krävs).
    • Målcontainer. I den här containern lagras dina översatta filer (krävs).

Auktorisering av lagringscontainer

Du kan välja något av följande alternativ för att auktorisera åtkomst till din Translator-resurs.

✔️ Hanterad identitet. En hanterad identitet är ett huvudnamn för tjänsten som skapar en Microsoft Entra-identitet och specifika behörigheter för en Azure-hanterad resurs. Med hanterade identiteter kan du köra ditt Translator-program utan att behöva bädda in autentiseringsuppgifter i koden. Hanterade identiteter är ett säkrare sätt att bevilja åtkomst till lagringsdata och ersätta kravet på att du ska inkludera signaturtoken för delad åtkomst (SAS) med dina käll- och mål-URL:er.

Mer information finns i Hanterade identiteter för dokumentöversättning.

Skärmbild av hanterat identitetsflöde (RBAC).

✔️ Signatur för delad åtkomst (SAS). En signatur för delad åtkomst är en URL som ger begränsad åtkomst under en angiven tidsperiod till din Translator-tjänst. Om du vill använda den här metoden måste du skapa SAS-token (Signatur för delad åtkomst) för dina käll- och målcontainrar. Och sourceUrl targetUrl måste innehålla en SAS-token (Signatur för delad åtkomst) som läggs till som en frågesträng. Token kan tilldelas till din container eller specifika blobar.

  • Källcontainern eller bloben måste ange läs- och liståtkomst.
  • Målcontainern eller bloben måste ange skriv- och liståtkomst.

Mer information finns i Skapa SAS-token.

Skärmbild av en resurs-URI med en SAS-token.

Skapa ditt program

Det finns flera tillgängliga verktyg för att skapa, skapa och köra Translator C#/.NET-program. Här vägleder vi dig genom att använda antingen kommandoradsgränssnittet (CLI) eller Visual Studio. Välj någon av följande flikar för att komma igång:

Konfigurera projektet

I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du dotnet new kommandot för att skapa en ny konsolapp med namnet batch-document-translation. Det här kommandot skapar ett enkelt "Hello World"-C#-projekt med en enda källfil: Program.cs.

dotnet new console -n batch-document-translation

Ändra katalogen till den nyligen skapade appmappen. Skapa ditt program med följande kommando:

dotnet build

Kompileringsutdata får inte innehålla några varningar eller fel.

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

Installera klientbiblioteket

Installera klientbiblioteket för dokumentöversättning för .NET i programkatalogen:

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

Översätta dokument asynkront

  1. För det här projektet behöver du ett källdokument som laddats upp till källcontainern. Du kan ladda ned vårt exempeldokument för dokumentöversättning för den här snabbstarten. Källspråket är engelska.

  2. Öppna filen Program.cs i önskad redigerare eller IDE från projektkatalogen. Ta bort den befintliga koden, inklusive raden Console.WriteLine("Hello World!").

  3. I programmets Program.cs skapar du variabler för nyckeln och den anpassade slutpunkten. Mer information finns i Hämta din nyckel och din anpassade domänslutpunkt.

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

  4. StartTranslationAsync Anropa metoden för att starta en översättningsåtgärd för ett eller flera dokument i en enda blobcontainer.

  5. Om du vill anropa StartTranslationAsyncmåste du initiera ett DocumentTranslationInput objekt som innehåller parametrarna sourceUri, targetUrioch targetLanguageCode :

    • För auktorisering av hanterad identitet skapar du följande variabler:

      • sourceUri. URL:en för källcontainern som innehåller dokument som ska översättas.

      • targetUri URL:en för målcontainern som de översatta dokumenten skrivs till.

      • targetLanguageCode. Språkkoden för de översatta dokumenten. Du hittar språkkoder på vår språksupportsida .

        Om du vill hitta käll- och mål-URL:er går du till ditt lagringskonto i Azure Portal. I det vänstra sidofältet går du till Datalagring och väljer Containrar och följer dessa steg för att hämta källdokumenten och målcontainern URLS.

        Source Target
        1. Markera kryssrutan bredvid källcontainern 1. Markera kryssrutan bredvid målcontainern.
        2. Från huvudfönstret väljer du en fil eller dokument för översättning. 2. Välj de ellipser som finns till höger och välj sedan Egenskaper.
        3. Käll-URL:en finns överst i listan Egenskaper. 3. Mål-URL:en finns överst i listan Egenskaper.

    • För sas-auktorisering (signatur för delad åtkomst) skapar du dessa variabler

      • sourceUri. SAS-URI:n, med en SAS-token som läggs till som en frågesträng, för att källcontainern som innehåller dokument ska översättas.
      • targetUri SAS-URI:n, med en SAS-token som läggs till som en frågesträng, för målcontainern som de översatta dokumenten skrivs till.
      • targetLanguageCode. Språkkoden för de översatta dokumenten. Du hittar språkkoder på vår språksupportsida .

Viktigt!

Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Key Vault. Mer information finns i Säkerhet för Azure AI-tjänster.

Exempel på asynkron översättningskod

Ange följande kodexempel i programmets Program.cs-fil:


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

Köra ditt program

När du har lagt till kodexemplet i programmet kör du programmet från projektkatalogen genom att skriva följande kommando i terminalen:

  dotnet run

Här är ett kodfragment av förväntade utdata:

Skärmbild av Visual Studio Code-utdata i terminalfönstret.

Exempel på synkron översättningskod

Du kan ladda ned vårt exempeldokument för dokumentöversättning för den här snabbstarten. Källspråket är engelska.



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

Det var allt! Du har precis skapat ett program för att översätta dokument i en lagringscontainer med hjälp av .NET-klientbiblioteket.

Konfigurera projektet

Kontrollera att den senaste versionen av Python är installerad.

Installera klientbiblioteket

Installera den senaste versionen av klientbiblioteket för dokumentöversättning:

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

Översätta batchfiler

  1. För det här projektet behöver du ett källdokument som laddats upp till källcontainern. Du kan ladda ned vårt exempeldokument för dokumentöversättning för den här snabbstarten. Källspråket är engelska.

  2. Skapa variabler för resursnyckeln och den anpassade slutpunkten i Python-programfilen. Mer information finns i Hämta din nyckel och din anpassade domänslutpunkt.

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

  1. Initiera ett DocumentTranslationClient objekt som innehåller parametrarna endpoint och key .

  2. begin_translation Anropa metoden och skicka parametrarna sourceUri, targetUrioch targetLanguageCode .

    • För auktorisering av hanterad identitet skapar du följande variabler:

      • sourceUri. URL:en för källcontainern som innehåller dokument som ska översättas.

      • targetUri URL:en för målcontainern som de översatta dokumenten skrivs till.

      • targetLanguageCode. Språkkoden för de översatta dokumenten. Du hittar språkkoder på vår språksupportsida .

        Om du vill hitta käll- och mål-URL:er går du till ditt lagringskonto i Azure Portal. I det vänstra sidofältet går du till Datalagring och väljer Containrar och följer dessa steg för att hämta källdokumenten och målcontainern URLS.

        Source Target
        1. Markera kryssrutan bredvid källcontainern 1. Markera kryssrutan bredvid målcontainern.
        2. Från huvudfönstret väljer du en fil eller dokument för översättning. 2. Välj de ellipser som finns till höger och välj sedan Egenskaper.
        3. Käll-URL:en finns överst i listan Egenskaper. 3. Mål-URL:en finns överst i listan Egenskaper.

    • För sas-auktorisering (signatur för delad åtkomst) skapar du dessa variabler

      • sourceUri. SAS-URI:n, med en SAS-token som läggs till som en frågesträng, för att källcontainern som innehåller dokument ska översättas.
      • targetUri SAS-URI:n, med en SAS-token som läggs till som en frågesträng, för målcontainern som de översatta dokumenten skrivs till.
      • targetLanguageCode. Språkkoden för de översatta dokumenten. Du hittar språkkoder på vår språksupportsida .

Exempel på asynkron översättningskod

Viktigt!

Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Key Vault. Mer information finns i Säkerhet för Azure AI-tjänster.

Ange följande kodexempel i Python-programmet:


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

Köra ditt program

När du har lagt till kodexemplet i programmet skriver du följande kommando i terminalen:

python asynchronous-sdk.py

Här är ett kodfragment av förväntade utdata:

Skärmbild av Python-utdata i terminalfönstret.

Exempel på synkron översättningskod

Du kan ladda ned vårt exempeldokument för dokumentöversättning för den här snabbstarten. Källspråket är engelska.

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

Det var allt! Du har precis skapat ett program för att översätta dokument asynkront och synkront med hjälp av Python-klientbiblioteket.

Gå vidare

Läs mer om åtgärder för dokumentöversättning