Condividi tramite

Introduzione: Raccolte client di traduzione documenti

  • Articolo

Traduzione di documenti è una funzionalità basata sul cloud del servizio Traduttore per Azure AI che converte in modo asincrono interi documenti in lingue supportate e vari formati di file. In questa guida introduttiva si apprenderà come usare la traduzione di documenti con un linguaggio di programmazione preferito per tradurre un documento di origine in un linguaggio di destinazione mantenendo al tempo stesso la struttura e la formattazione del testo.

Importante

  • La traduzione di documenti è attualmente supportata solo nella risorsa Traduttore (a servizio singolo) e non è inclusa nella risorsa Servizi di Azure AI (multiservizio).
  • La traduzione di documenti è supportata nei livelli a pagamento. Language Studio supporta solo i livelli di istanza S1 o D3. È consigliabile selezionare Standard S1 per provare la traduzione di documenti. VederePrezzi dei Servizi di Azure AI - Traduttore.
  • Le versioni di anteprima pubblica di Traduzione documenti consentono l'accesso anticipato alle funzionalità in fase di sviluppo attivo. Le funzionalità, gli approcci e i processi possono cambiare prima della disponibilità generale, a seconda del feedback degli utenti.
  • La versione di anteprima pubblica delle librerie client di traduzione documenti è predefinita l'API REST versione 2024-05-01.

Prerequisiti

Per iniziare, è necessario:

Autorizzazione del contenitore di archiviazione

È possibile scegliere una delle opzioni seguenti per autorizzare l'accesso alla risorsa Traduttore.

✔️ Identità gestita. Un'identità gestita è un'entità servizio che crea un'identità Microsoft Entra e autorizzazioni specifiche per una risorsa gestita di Azure. Le identità gestite consentono di eseguire l'applicazione Traduttore senza dover incorporare le credenziali nel codice. Le identità gestite sono un modo più sicuro per concedere l'accesso ai dati di archiviazione e sostituire il requisito per includere i token di firma di accesso condiviso con gli URL di origine e di destinazione.

Per altre informazioni, vedereIdentità gestite per la traduzione di documenti.

Screenshot del flusso di identità gestito.

✔️ Firma di accesso condiviso (SAS). Una firma di accesso condiviso è un URL che concede l'accesso limitato per un periodo di tempo specificato al servizio Traduttore. Per usare questo metodo, è necessario creare token di firma di accesso condiviso per i contenitori di origine e di destinazione. sourceUrl e targetUrl devono includere un token di firma di accesso condiviso (SAS), aggiunto come stringa di query. Il token può essere assegnato al contenitore o a BLOB specifici.

  • Il contenitore o il BLOB di origine deve designare l'accesso di lettura ed elenco.
  • Il contenitore o il BLOB di destinazione deve designare l'accesso di lettura ed elenco.

Per altre informazioni, vedereCreare token di firma di accesso condiviso.

Screenshot di un URI di risorsa con un token di firma di accesso condiviso.

Compilare l'applicazione

Sono disponibili diversi strumenti per la creazione, la compilazione e l'esecuzione di applicazioni Traduttore C#/.NET. In questa sezione viene illustrato come usare l'interfaccia della riga di comando o Visual Studio. Selezionare una delle schede seguenti per iniziare:

Impostare il progetto

In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome batch-document-translation. Questo comando crea un semplice progetto C# "Hello World" con un singolo file di origine: Program.cs.

dotnet new console -n batch-document-translation

Spostarsi nella cartella dell'app appena creata. Compilare l'applicazione con il comando seguente:

dotnet build

L'output di compilazione non deve contenere alcun avviso o errore.

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

Installare la libreria client

Nella directory dell'applicazione installare la libreria client di traduzione di documenti per .NET:

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

Tradurre un documento o file batch

  1. Per questo progetto è necessario un documento di origine caricato nel contenitore di origine. Per questo avvio rapido, è possibile scaricare il documento di esempio di Traduzione di documenti. La lingua di origine è l'inglese.

  2. Dalla directory del progetto aprire il file Program.cs nell'ambiente di sviluppo integrato o nell'editor preferito. Eliminare il codice preesistente, inclusa la riga Console.WriteLine("Hello World!").

  3. In Program.cs dell'applicazione creare le variabili per l'endpoint personalizzato e la chiave. Per altre informazioni, vedereRecuperare la chiave e l'endpoint di dominio personalizzato.

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

  4. Chiamare il metodo StartTranslationAsync per avviare un'operazione di conversione per uno o più documenti in un singolo contenitore BLOB.

  5. Per chiamare StartTranslationAsync, è necessario inizializzare un oggetto DocumentTranslationInput contenente i parametri sourceUri, targetUri e targetLanguageCode:

    • Per Autorizzazione dell'identità gestita creare queste variabili:

      • sourceUri. URL del contenitore di origine con i documenti da tradurre.

      • targetUri URL per il contenitore di destinazione in cui vengono scritti i documenti tradotti.

      • targetLanguageCode. Codice linguistico per i documenti tradotti. Puoi trovare i codici linguistici nella pagina Lingue supportate.

        Per trovare gli URL di origine e di destinazione, passare all'account di archiviazione nel portale di Azure. Nella barra laterale sinistra, in Archiviazione dati selezionare Contenitori e seguire questa procedura per recuperare i documenti di origine e il contenitore di destinazione URLS.

        Origine Target
        1. Selezionare la casella di controllo accanto al contenitore di origine 1. Selezionare la casella di controllo accanto al contenitore di destinazione.
        2. Nell'area della finestra principale selezionare un file o i documenti per la traduzione. 2. Selezionare i puntini di sospensione a destra, quindi scegliere Proprietà.
        3. L'URL di origine si trova nella parte superiore dell'elenco Proprietà. 3. L'URL di destinazione si trova nella parte superiore dell'elenco Proprietà.

    • Per Autenticazione della firma di accesso condiviso (SAS) creare queste variabili

      • sourceUri. L'URI di firma di accesso condiviso, con un token di firma di accesso condiviso aggiunto come stringa di query, per il contenitore di origine contenente documenti da tradurre.
      • targetUri L'URI di firma di accesso condiviso, con un token di firma di accesso condiviso aggiunto come stringa di query, per il contenitore di destinazione in cui vengono scritti i documenti tradotti.
      • targetLanguageCode. Codice linguistico per i documenti tradotti. Puoi trovare i codici linguistici nella pagina Lingue supportate.

Esempio di codice

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, utilizzare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedereSicurezza di Servizi di Azure AI.

Immettere l'esempio di codice seguente nel file Program.cs dell'applicazione:


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

Eseguire l'applicazione

Dopo aver aggiunto l'esempio di codice all'applicazione, eseguire l'applicazione dalla directory del progetto digitando il comando seguente nel terminale:

  dotnet run

Ecco un frammento di output previsto:

Screenshot dell'output di Visual Studio Code nella finestra del terminale.

Ecco fatto! È stato appena creato un programma per tradurre i documenti in un contenitore di archiviazione usando la libreria client .NET.

Impostare il progetto

Assicurarsi che sia installata la versione più recente di Python.

Installare la libreria client

Installare la versione più recente della libreria client di Traduzione di documenti:

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

Tradurre un documento o file batch

  1. Per questo progetto è necessario un documento di origine caricato nel contenitore di origine. Per questo avvio rapido, è possibile scaricare il documento di esempio di Traduzione di documenti. La lingua di origine è l'inglese.

  2. Nel file dell'applicazione Python creare variabili per la chiave di risorsa e l'endpoint personalizzato. Per altre informazioni, vedereRecuperare la chiave e l'endpoint di dominio personalizzato.

key = "<your-key>"
endpoint = "<your-custom-endpoint>"

  1. Inizializzare un oggetto DocumentTranslationClient contenente i parametri endpoint e key.

  2. Chiamare il metodo begin_translation e passare i parametri sourceUri, targetUri e targetLanguageCode.

    • Per Autorizzazione dell'identità gestita creare queste variabili:

      • sourceUri. URL del contenitore di origine con i documenti da tradurre.

      • targetUri URL per il contenitore di destinazione in cui vengono scritti i documenti tradotti.

      • targetLanguageCode. Codice linguistico per i documenti tradotti. Puoi trovare i codici linguistici nella pagina Lingue supportate.

        Per trovare gli URL di origine e di destinazione, passare all'account di archiviazione nel portale di Azure. Nella barra laterale sinistra, in Archiviazione dati selezionare Contenitori e seguire questa procedura per recuperare i documenti di origine e il contenitore di destinazione URLS.

        Origine Target
        1. Selezionare la casella di controllo accanto al contenitore di origine 1. Selezionare la casella di controllo accanto al contenitore di destinazione.
        2. Nell'area della finestra principale selezionare un file o i documenti per la traduzione. 2. Selezionare i puntini di sospensione a destra, quindi scegliere Proprietà.
        3. L'URL di origine si trova nella parte superiore dell'elenco Proprietà. 3. L'URL di destinazione si trova nella parte superiore dell'elenco Proprietà.

    • Per Autenticazione della firma di accesso condiviso (SAS) creare queste variabili

      • sourceUri. L'URI di firma di accesso condiviso, con un token di firma di accesso condiviso aggiunto come stringa di query, per il contenitore di origine contenente documenti da tradurre.
      • targetUri L'URI di firma di accesso condiviso, con un token di firma di accesso condiviso aggiunto come stringa di query, per il contenitore di destinazione in cui vengono scritti i documenti tradotti.
      • targetLanguageCode. Codice linguistico per i documenti tradotti. Puoi trovare i codici linguistici nella pagina Lingue supportate.

Codice di esempio

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, utilizzare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedereSicurezza di Servizi di Azure AI.

Immettere l'esempio di codice seguente nell'applicazione 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-key>"
endpoint = "<your-custom-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 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
            )
        )

Eseguire l'applicazione

Dopo aver aggiunto l'esempio di codice all'applicazione, digitare il comando seguente nel terminale:

python asynchronous-sdk.py

Ecco un frammento di output previsto:

Screenshot dell'output python nella finestra del terminale.

Ecco fatto! È stato appena creato un programma per tradurre i documenti in un contenitore di archiviazione usando la libreria client Python.

Passaggio successivo

Altre informazioni sulle operazioni di Traduzione di documenti