Condividi tramite

Guida introduttiva: librerie client per il testo di Azure AI Translator

In questo argomento di avvio rapido è possibile iniziare a usare il servizio Traduttore per tradurre il testo usando un linguaggio di programmazione preferito. Per questo progetto, è consigliabile usare il piano tariffario gratuito (F0), mentre si sta imparando la tecnologia e successivamente si esegue l'aggiornamento a un livello a pagamento per la produzione.

Prerequisiti

È necessaria una sottoscrizione di Azure attiva. Se non si ha una sottoscrizione di Azure, è possibile crearne una gratuitamente

  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa Translator nel portale di Azure.

  • Dopo la distribuzione della risorsa, selezionare Vai alla risorsa e recuperare la chiave e l'endpoint.

    • Ottenere la chiave, l'endpoint e l'area dalla risorsa e connettere l'applicazione al servizio Translator. Incolla questi valori nel codice più avanti nella guida rapida. È possibile trovarli nella pagina Chiavi ed endpoint del portale di Azure:

      Screenshot: pagina delle chiavi e dell'endpoint del portale di Azure.

Configurare l'ambiente C#/.NET

In questo avvio rapido si usa la versione più recente dell'IDE di Visual Studio per creare ed eseguire l'applicazione.

  1. Avvia Visual Studio.

  2. Nella pagina Attività iniziali scegliere Crea un nuovo progetto.

    Screenshot della finestra introduttiva di Visual Studio 2022.

  3. Nella pagina Crea un nuovo progetto immettere console nella casella di ricerca. Scegliere il modello Applicazione console, quindi selezionare Avanti.

    Screenshot della pagina Crea nuovo progetto di Visual Studio 2022.

  4. Nella finestra di dialogo Configura il nuovo progetto immettere text-translation-sdk nella casella Nome progetto. Scegliere quindi Avanti.

    Screenshot della finestra di configurazione del nuovo progetto di Visual Studio 2022.

  5. Nella finestra di dialogo Altre informazioni assicurarsi che sia selezionata l'opzione .NET 6.0 (supporto a lungo termine) e quindi selezionare Crea.

    Screenshot della finestra informazioni aggiuntive di Visual Studio 2022.

Installare la libreria client con NuGet

  1. Fare clic con il pulsante destro del mouse sul progetto Translator-text-sdk e scegliere Manage NuGet Packages...Screenshot della finestra del pacchetto NuGet in Visual Studio.

  2. Selezionare la Browse scheda e la Include prerelease casella di controllo e digitare Azure.AI.Translation.Text.

    Screenshot della selezione del pacchetto NuGet 'prerelease' in Visual Studio.

  3. Selezionare la versione 1.0.0-beta.1 dal menu a discesa e installare il pacchetto nel progetto.

    Screenshot dell'installazione del pacchetto NuGet 'prerelease' in Visual Studio.

Compilare l'applicazione

Per interagire con il servizio Translator usando la libreria client, è necessario creare un'istanza della TextTranslationClientclasse . A tale scopo, crea un AzureKeyCredential con il tuo key dal portale di Azure e un'istanza TextTranslationClient con il AzureKeyCredential. L'autenticazione varia leggermente a seconda che la risorsa usi l'endpoint globale o regionale. Per questo progetto, eseguire l'autenticazione usando l'endpoint globale. Per ulteriori informazioni sull'uso di un endpoint regionale, vedereSDK Traduttore testuale.

Annotazioni

  • A partire da .NET 6, i nuovi progetti che usano il modello console generano un nuovo stile di programma, diverso dalle versioni precedenti.
  • Il nuovo output usa le funzionalità C# recenti che semplificano il codice da scrivere.
  • Quando si usa la versione più recente, è sufficiente scrivere il corpo del metodo Main. Non è necessario includere istruzioni di primo livello, direttive d'uso globali o implicite.
  • Per altre informazioni, vederei nuovi modelli di C# generano istruzioni di primo livello.

  1. Aprire il file Program.cs.

  2. Eliminare il codice esistente, inclusa la riga Console.WriteLine("Hello World!"), e immettere l'esempio di codice seguente nel file di Program.cs dell'applicazione:

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, vederel'articolo sulla sicurezza di Servizi di Azure AI.

Tradurre un testo

Annotazioni

In questo esempio viene usato l'endpoint globale. Se si usa un endpoint a livello di area, vedere Creare un client di traduzione testuale.


using Azure;
using Azure.AI.Translation.Text;


string key = "<your-key>";

AzureKeyCredential credential = new(key);
TextTranslationClient client = new(credential);

try
{
    string targetLanguage = "fr";
    string inputText = "This is a test.";

    Response<IReadOnlyList<TranslatedTextItem>> response = await client.TranslateAsync(targetLanguage, inputText).ConfigureAwait(false);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;
    TranslatedTextItem translation = translations.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {translation?.DetectedLanguage?.Language} with score: {translation?.DetectedLanguage?.Score}.");
    Console.WriteLine($"Text was translated to: '{translation?.Translations?.FirstOrDefault().To}' and the result is: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Eseguire l'applicazione

Dopo aver aggiunto l'esempio di codice all'applicazione, scegliere il pulsante verde di avvio accanto a formRecognizer_quickstart per compilare ed eseguire il programma oppure premere F5.

Screenshot: eseguire il programma Visual Studio.

Ecco un frammento dell'output previsto:

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

Configurare l'ambiente Java

Annotazioni

Azure Text Translation SDK per Java è testato e supportato nelle piattaforme Windows, Linux e macOS. Non viene testato in altre piattaforme e non supporta le distribuzioni Android.

Per questa guida introduttiva si usa lo strumento di automazione della compilazione Gradle per creare ed eseguire l'applicazione.

  • È necessario avere la versione più recente di Visual Studio Code o l'IDE preferito. VedereJava in Visual Studio Code.

    Suggerimento

    • Visual Studio Code offre un Coding Pack per Java per Windows e macOS. Il Coding Pack è un bundle di VS Code, Java Development Kit (JDK) e una raccolta di estensioni suggerite da Microsoft. Il Coding Pack può essere usato anche per correggere un ambiente di sviluppo esistente.
    • Se si usano VS Code e Coding Pack per Java, installare l'estensione Gradle per Java.

  • Se non si usa Visual Studio Code, assicurarsi di avere installato quanto segue nell'ambiente di sviluppo:

Creare un nuovo progetto Gradle

  1. Nella finestra della console ,ad esempio cmd, PowerShell o Bash, creare una nuova directory per l'app denominata text-translation-app e passare a essa.

    mkdir text-translation-app && text-translation-app

    mkdir text-translation-app; cd text-translation-app

  2. Eseguire il comando gradle init dalla directory text-translation-app. Questo comando crea i file di compilazione essenziali per Gradle, tra cui build.gradle.kts, che viene usato in fase di esecuzione per creare e configurare l'applicazione.

    gradle init --type basic

  3. Quando viene richiesto di scegliere un linguaggio DSL, selezionare Kotlin.

  4. Accettare il nome del progetto predefinito (text-translation-app) selezionando Restituisci o Immetti.

    Annotazioni

    La creazione dell'intera applicazione potrebbe richiedere alcuni minuti, ma presto verranno visualizzati diversi file e cartelle, tra cui build-gradle.kts.

  5. Aggiornare build.gradle.kts con il codice seguente. La classe principale è Translate:

      plugins {
  java
  application
}
application {
  mainClass.set("Translate")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation("com.azure:azure-ai-translation-text:1.0.0-beta.1")
}

Creare l'applicazione Java

  1. Dalla directory text-translation-app eseguire il comando seguente:

    mkdir -p src/main/java

    Il comando crea la struttura di directory seguente:

    Screenshot della struttura di directory di Java.

  2. Passare alla directory java e creare un file denominato Translate.java.

    Suggerimento

    • È possibile creare un nuovo file usando PowerShell.

    • Tenendo premuto il tasto MAIUSC e facendo clic con il pulsante destro del mouse sulla cartella, aprire una finestra di PowerShell nella directory del progetto.

    • Immettere il comando seguente New-Item Translate.java.

    • È anche possibile creare un nuovo file nell'IDE denominato Translate.java e salvarlo nella directory java.

  3. Copiare e incollare l'esempio di codice di traduzione del testo seguente nel file Translate.java .

    • ** Aggiorna "<your-key>", "<your-endpoint>" e "<region>" con i valori dell'istanza Translator del tuo portale Azure.

Esempio di codice

Tradurre un testo

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, vederel'articolo sulla sicurezza di Servizi di Azure AI.

Per interagire con il servizio Translator usando la libreria client, è necessario creare un'istanza della TextTranslationClientclasse . A tale scopo, creare un AzureKeyCredential con il tuo key dal portale di Azure e un'istanza TextTranslationClient con il AzureKeyCredential. L'autenticazione varia leggermente a seconda che la risorsa usi l'endpoint globale o regionale. Per questo progetto, eseguire l'autenticazione usando l'endpoint globale. Per ulteriori informazioni sull'uso di un endpoint regionale, vedereSDK di traduzione testuale.

Annotazioni

In questo esempio viene usato l'endpoint globale. Se si usa un endpoint a livello di area, vedere Creare un client di traduzione testuale.

import java.util.List;
import java.util.ArrayList;
import com.azure.ai.translation.text.models.*;
import com.azure.ai.translation.text.TextTranslationClientBuilder;
import com.azure.ai.translation.text.TextTranslationClient;

import com.azure.core.credential.AzureKeyCredential;
/**
 * Translate text from known source language to target language.
 */
public class Translate {

    public static void main(String[] args) {
        String apiKey = "<your-key>";
        AzureKeyCredential credential = new AzureKeyCredential(apiKey);

        TextTranslationClient client = new TextTranslationClientBuilder()
                .credential(credential)
                .buildClient();

        String from = "en";
        List<String> targetLanguages = new ArrayList<>();
        targetLanguages.add("es");
        List<InputTextItem> content = new ArrayList<>();
        content.add(new InputTextItem("This is a test."));

        List<TranslatedTextItem> translations = client.translate(targetLanguages, content, null, from, TextType.PLAIN, null, null, null, false, false, null, null, null, false);

        for (TranslatedTextItem translation : translations) {
            for (Translation textTranslation : translation.getTranslations()) {
                System.out.println("Text was translated to: '" + textTranslation.getTo() + "' and the result is: '" + textTranslation.getText() + "'.");
            }
        }
    }
}

Compilare ed eseguire l'applicazione**

Dopo aver aggiunto l'esempio di codice all'applicazione, tornare alla directory principale del progetto, text-translation-app.

  1. Compilare l'applicazione con il build comando (si dovrebbe ricevere un messaggio BUILD SUCCESSFUL ):

    gradle build

  2. Eseguire l'applicazione con il run comando (si dovrebbe ricevere un messaggio BUILD SUCCESSFUL ):

    gradle run

Ecco un frammento dell'output previsto:

Screenshot dell'output Java nella finestra del terminale.

Imposta il tuo ambiente Node.js

Per questa guida introduttiva si usa l'ambiente di runtime JavaScript Node.js per creare ed eseguire l'applicazione.

  1. Assicurarsi di avere la versione più recente di Node.js. Node Package Manager (npm) è incluso nell'installazione Node.js.

    Suggerimento

    Se non si ha familiarità con Node.js, provare il modulo di Learn Introduzione a Node.js.

  2. In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app denominata text-translation-app.

    mkdir text-translation-app && cd text-translation-app

    mkdir text-translation-app; cd text-translation-app

  3. Eseguire il comando npm init per inizializzare l'applicazione ed eseguire lo scaffolding del progetto.

    npm init

  4. Specificare gli attributi del progetto accettando le richieste presentate nel terminale.

    • Gli attributi più importanti sono nome, numero di versione e punto di ingresso.
    • È consigliabile mantenere index.js per il nome del punto di ingresso. La descrizione, il comando di test, il repository GitHub, le parole chiave, l'autore e le informazioni sulla licenza sono attributi facoltativi, ma possono essere ignorati per questo progetto.
    • Accettare i suggerimenti tra parentesi selezionando Torna o Invio.
    • Dopo aver completato le istruzioni, verrà creato un file package.json nella directory text-translation-app.

Installare la libreria client

Aprire una finestra del terminale e installare la Azure Text translation libreria client per JavaScript con npm:

npm i @azure-rest/ai-translation-text@1.0.0-beta.1

Compilare l'applicazione

Per interagire con il servizio Translator usando la libreria client, è necessario creare un'istanza della TextTranslationClientclasse . A tale scopo, creare un TranslateCredential con i tuoi key e <region> dal portale di Azure e un'istanza TextTranslationClient. Per ulteriori informazioni, vedereSDK di traduzione testuale.

  1. Creare il index.js file nella directory dell'app.

    Suggerimento

    • È possibile creare un nuovo file usando PowerShell.

    • Tenendo premuto il tasto MAIUSC e facendo clic con il pulsante destro del mouse sulla cartella, aprire una finestra di PowerShell nella directory del progetto.

    • Immettere il comando seguente New-Item index.js.

    • È anche possibile creare un nuovo file denominato index.js nell'IDE e salvarlo nella directorytext-translation-app.

  2. Copiare e incollare l'esempio di codice di traduzione del testo seguente nel index.js file. Aggiornare <your-endpoint> e <your-key> con i valori dell'istanza del servizio Translator nel portale di Azure.

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, vedere Sicurezza dei servizi di intelligenza artificiale di Azure.

Tradurre un testo

Annotazioni

In questo esempio viene usato un endpoint a livello di area. Se si usa l'endpoint globale, vedere Creare un client di traduzione testuale.

const TextTranslationClient = require("@azure-rest/ai-translation-text").default

const apiKey = "<your-key>";
const endpoint = "<your-endpoint>";
const region = "<region>";

async function main() {

  console.log("== Text translation sample ==");

  const translateCredential = {
    key: apiKey,
    region,
  };
  const translationClient = new TextTranslationClient(endpoint,translateCredential);

  const inputText = [{ text: "This is a test." }];
  const translateResponse = await translationClient.path("/translate").post({
    body: inputText,
    queryParameters: {
      to: "fr",
      from: "en",
    },
  });

  const translations = translateResponse.body;
  for (const translation of translations) {
    console.log(
      `Text was translated to: '${translation?.translations[0]?.to}' and the result is: '${translation?.translations[0]?.text}'.`
    );
  }
}

main().catch((err) => {
    console.error("An error occurred:", err);
    process.exit(1);
  });

  module.exports = { main };

Eseguire l'applicazione

Dopo aver aggiunto l'esempio di codice all'applicazione, eseguire il programma:

  1. Passare alla cartella in cui si dispone dell'applicazione di traduzione testuale (text-translation-app).

  2. Digitare il comando seguente nel terminale:

    node index.js

Ecco un frammento dell'output previsto:

Screenshot dell'output di JavaScript nella finestra del terminale.

Configurare il progetto Python

  1. Assicurarsi di avere la versione più recente di Python 3.x. Il pacchetto del programma di installazione Python (pip) è incluso nell'installazione di Python.

    Suggerimento

    Se non si ha familiarità con Python, provare il modulo di Learn Introduzione a Python.

  2. Aprire una finestra del terminale e installare la Azure Text translation libreria client per Python con pip:

    pip install azure-ai-translation-text==1.0.0b1

Compilare l'applicazione

Per interagire con il servizio Translator usando la libreria client, è necessario creare un'istanza della TextTranslationClientclasse . A tale scopo, crea un TranslatorCredential con il tuo key dal portale di Azure e un'istanza TextTranslationClient. Per altre informazioni, vedereSDK di traduzione testuale.

  1. Creare un nuovo file Python denominato text-translation-app.py nell'editor o nell'IDE preferito.

  2. Copia e incolla il codice di esempio di traduzione del testo seguente nel file text-translation-app.py. Aggiorna <your-key>, <your-endpoint>, e <region> con i valori dell'istanza di Translator nell'Azure portal.

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, vederel'articolo sulla sicurezza di Servizi di Azure AI.

Tradurre un testo

Annotazioni

In questo esempio viene usato un endpoint a livello di area. Se si usa l'endpoint globale, vedere Creare un client di traduzione testuale.

from azure.ai.translation.text import TextTranslationClient, TranslatorCredential
from azure.ai.translation.text.models import InputTextItem
from azure.core.exceptions import HttpResponseError

# set `<your-key>`, `<your-endpoint>`, and  `<region>` variables with the values from the Azure portal
key = "<your-key>"
endpoint = "<your-endpoint>"
region = "<region>"

credential = TranslatorCredential(key, region)
text_translator = TextTranslationClient(endpoint=endpoint, credential=credential)

try:
    source_language = "en"
    target_languages = ["es", "it"]
    input_text_elements = [ InputTextItem(text = "This is a test") ]

    response = text_translator.translate(content = input_text_elements, to = target_languages, from_parameter = source_language)
    translation = response[0] if response else None

    if translation:
        for translated_text in translation.translations:
            print(f"Text was translated to: '{translated_text.to}' and the result is: '{translated_text.text}'.")

except HttpResponseError as exception:
    print(f"Error Code: {exception.error.code}")
    print(f"Message: {exception.error.message}")

Eseguire l'applicazione

Dopo aver aggiunto l'esempio di codice all'applicazione, compilare ed eseguire il programma:

Passare alla cartella in cui si dispone del file text-translation-app.py .

Digitare il comando seguente nel terminale:

python text-translation-app.py

Ecco un frammento dell'output previsto:

Screenshot dell'output di JavaScript nella finestra del terminale.

Ecco fatto, congratulazioni! In questa guida introduttiva è stato usato un SDK per la traduzione testuale per tradurre il testo.

Passaggi successivi

Altre informazioni sulle opzioni di sviluppo della traduzione testuale:

Panoramica dell'SDK di traduzione testuale

Riferimento alla traduzione testuale V3