Contenitore: Tradurre testo

Tradurre un testo.

Richiesta URL

Inviare una richiesta POST a:

POST http://localhost:{port}/translate?api-version=3.0&&from={from}&to={to}

Richiesta di esempio

curl -x POST "https:localhost:5000/translate?api-version=3.0&from=en&to=es" -H "Content-Type: application/json" -d "[{
'Text': 'I would really like to drive your car.'}]"

Esempio di risposta

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

Parametri della richiesta

I parametri della richiesta inviati a una stringa di query sono:

Parametri obbligatori

• È possibile eseguire query sul servizio per individuare translation le lingue supportate per l'ambito.
• Vedere anche Supporto del linguaggio per la traslitterazione.

Parametri facoltativi

Intestazioni delle richieste

Testo della richiesta

Il corpo della richiesta è una matrice JSON. Ogni elemento di matrice è un oggetto JSON con una proprietà di stringa denominata Text, che rappresenta la stringa da tradurre.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

Si applicano le limitazioni seguenti:

• La matrice deve essere composta al massimo da 100 elementi.
• L'intero testo incluso nella richiesta non può superare i 50.000 caratteri, inclusi gli spazi.

Corpo della risposta

Una risposta corretta è una matrice JSON con un risultato per ogni stringa nella matrice di input. Un oggetto risultato include le proprietà seguenti:

• translations: matrice dei risultati della traduzione. Le dimensioni della matrice corrispondono al numero di lingue di destinazione specificate tramite il parametro di query to. Ogni elemento nella matrice include:

• to: stringa che rappresenta il codice lingua della lingua di destinazione.

• text: stringa che fornisce il testo tradotto.

• sentLen: oggetto che restituisce delimitatori di frase nei testi di input e output.

• srcSentLen: matrice di interi che rappresenta le lunghezze delle frasi nel testo di input. La lunghezza della matrice è il numero di frasi e i valori sono la lunghezza di ogni frase.

• transSentLen: matrice di interi che rappresenta le lunghezze delle frasi nel testo tradotto. La lunghezza della matrice è il numero di frasi e i valori sono la lunghezza di ogni frase.

  I delimitatori di frase vengono inclusi solo quando il parametro della richiesta includeSentenceLength è true.

  • sourceText: oggetto con una proprietà di stringa singola denominata text, che fornisce il testo di input nel carattere predefinito della lingua di origine. La proprietà sourceText è presente solo quando l'input è espresso in un carattere che non è quello consueto per la lingua. Ad esempio, se l'input è in arabo scritto in caratteri dell'alfabeto latino, sourceText.text è lo stesso testo in arabo convertito in caratteri dell'alfabeto arabo.

Intestazioni della risposta

Codici di stato della risposta

Se si verifica un errore, la richiesta restituisce una risposta di errore JSON. Il codice errore è un numero a 6 cifre che combina il codice di stato HTTP a 3 cifre seguito da un numero a 3 cifre per classificare ulteriormente l'errore. I codici di errore più comuni sono reperibili nella pagina di riferimento Traduttore v3.

Esempi di codice: tradurre il testo

Tradurre un singolo input

Questo esempio mostra come tradurre una singola frase dall'inglese al cinese semplificato.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Il corpo della risposta è:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

La matrice translations include un elemento, che fornisce la traduzione della singola parte di testo nell'input.

Eseguire query sull'endpoint di Azure AI Translator (testo)

Ecco un esempio di richiesta HTTP cURL usando localhost:5000 specificato con il docker run comando :

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"
    -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

Tradurre testo con l'API Swagger

Inglese ↔ tedesco

1. Passare alla pagina Swagger: http://localhost:5000/swagger/index.html
2. Selezionare POST /translate
3. Selezionare Prova
4. Immettere il parametro Da come en
5. Immettere il parametro A come de
6. Immettere il parametro api-version come 3.0
7. In testi sostituire string con il JSON seguente

  [
        {
            "text": "hello, how are you"
        }
  ]

Selezionare Esegui. Le traduzioni risultanti vengono restituite nel corpo della risposta. Si dovrebbe vedere la risposta seguente:

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

Tradurre testo con Python

Inglese francese ↔

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

Tradurre testo con l'app console C#/.NET

Inglese spagnolo ↔

Avviare Visual Studio e creare una nuova applicazione console. Modificare il file *.csproj per aggiungere il nodo <LangVersion>7.1</LangVersion>, che specifica C# 7.1. Aggiungere il pacchetto NuGet Newtoonsoft.Json versione 11.0.2.

In Program.cs sostituire tutto il codice esistente con lo script seguente:

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

Tradurre più stringhe

La traduzione di più stringhe contemporaneamente equivale semplicemente a specificare una matrice di stringhe nel corpo della richiesta.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

La risposta contiene la traduzione di tutti i frammenti di testo nello stesso ordine della richiesta. Il corpo della risposta è:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Tradurre in più lingue

Questo esempio mostra come tradurre lo stesso input in diverse lingue in una sola richiesta.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Il corpo della risposta è:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Tradurre il contenuto con markup e specificare il contenuto tradotto

È comune tradurre contenuto che include markup, ad esempio contenuto da una pagina HTML o contenuto da un documento XML. Includere il parametro di query textType=html durante la traduzione di contenuto con tag. Inoltre, a volte è utile escludere contenuto specifico dalla traduzione. È possibile usare l'attributo class=notranslate per specificare il contenuto che deve rimanere nella lingua originale. Nell'esempio seguente il contenuto all'interno del primo div elemento non viene tradotto, mentre il contenuto nel secondo div elemento viene convertito.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

Ecco una richiesta di esempio da illustrare.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

La risposta è:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Tradurre con un dizionario dinamico

Se si conosce già la traduzione che si vuole applicare a una parola o una frase, è possibile specificarla come markup all'interno della richiesta. Il dizionario dinamico è sicuro solo per nomi appropriati, ad esempio nomi personali e nomi di prodotto.

Il markup da specificare usa la sintassi seguente.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

Si consideri ad esempio la frase inglese "La parola wordomatic è una voce di dizionario". Per mantenere la parola wordomatic nella traduzione, inviare la richiesta:

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

Il risultato è:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

Questa funzionalità funziona allo stesso modo con textType=text o con textType=html. È consigliabile usarla solo in casi limitati. Il modo più appropriato e di gran lunga migliore per personalizzare una traduzione è quello di usare Custom Translator. Custom Translator fa un ampio uso delle probabilità statistiche e di contesto. Se sono stati creati dati di training che mostrano il lavoro o la frase nel contesto, si ottengono risultati migliori. Altre informazioni su Custom Translator.

Limiti delle richieste

Ogni richiesta di traduzione è limitata a 50.000 caratteri, in tutte le lingue di destinazione in cui stai traducendo. Ad esempio, l'invio di una richiesta di traduzione di 3.000 caratteri per tradurre in tre lingue diverse comporta una dimensione della richiesta di 3000x3 = 9.000 caratteri, che soddisfano il limite di richieste. Sono previsti addebiti in base ai caratteri e non al numero di richieste. È consigliabile inviare richieste più brevi.

Nella tabella seguente sono elencati i limiti degli elementi della matrice e dei caratteri per l'operazione di traduzione di Translator.

Usare docker compose: Translator con contenitori di supporto

Docker compose è uno strumento che consente di configurare applicazioni multi-contenitore usando un singolo file YAML denominato compose.yamlin genere . Usare il comando docker compose up per avviare l'applicazione contenitore e il comando docker compose down per arrestare e rimuovere i contenitori.

Se è stata installata l'interfaccia della riga di comando di Docker Desktop, include Docker compose e i relativi prerequisiti. Se Docker Desktop non è disponibile, vedere la panoramica Installazione di Docker Compose.

Nella tabella seguente sono elencati i contenitori di supporto necessari per le operazioni di traduzione di testo e documenti. Il contenitore Traduttore invia informazioni di fatturazione ad Azure tramite la risorsa Traduttore per Azure AI nell'account Azure.

Immagini e tag del contenitore

Le immagini del contenitore dei Servizi di Azure AI sono disponibili nel catalogo del Registro artefatti Microsoft. La tabella seguente elenca il percorso completo dell'immagine per la traduzione di testi e documenti:

Creare l'applicazione

1. Usando l'editor o l'IDE preferito, creare una nuova directory per l'app denominata container-environment o un nome di propria scelta.

2. Creare un nuovo file YAML denominato compose.yaml. Entrambe le estensioni .yml o yaml possono essere usate per il file compose.

3. Copiare e incollare il codice di esempio YAML seguente nel file compose.yaml. Sostituire {TRANSLATOR_KEY} e {TRANSLATOR_ENDPOINT_URI} con i valori di chiave ed endpoint dell'istanza Traduttore del portale di Azure. Assicurarsi di usare .document translation endpoint

4. Il nome di primo livello (azure-ai-translator, azure-ai-language, azure-ai-read) è il parametro specificato.

5. container_name è un parametro facoltativo che imposta un nome per il contenitore durante l'esecuzione, anziché consentire a docker compose la generazione di un nome.

   services:
     azure-ai-translator:
       container_name: azure-ai-translator
       image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
       environment:
           - EULA=accept
           - billing={TRANSLATOR_ENDPOINT_URI}
           - apiKey={TRANSLATOR_KEY}
           - AzureAiLanguageHost=http://azure-ai-language:5000
           - AzureAiReadHost=http://azure-ai-read:5000
       ports:
             - "5000:5000"
       azure-ai-language:
         container_name: azure-ai-language
         image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
         environment:
             - EULA=accept
             - billing={TRANSLATOR_ENDPOINT_URI}
             - apiKey={TRANSLATOR_KEY}
       azure-ai-read:
         container_name: azure-ai-read
         image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
         environment:
             - EULA=accept
             - billing={TRANSLATOR_ENDPOINT_URI}
             - apiKey={TRANSLATOR_KEY}
   

6. Aprire un terminale passare alla cartella container-environment e avviare i contenitori con il comando docker-compose seguente:

   docker compose up
   

7. Per arrestare il contenitore, usare il comando seguente:

   docker compose down
   

   Suggerimento

   docker compose Comandi:

   • docker compose pause sospende i contenitori in esecuzione.
   • docker compose unpause {your-container-name} rimette in esecuzione i contenitori in pausa.
   • docker compose restart riavvia tutti i contenitori arrestati e in esecuzione con tutte le modifiche precedenti intatte. Se si apportano modifiche alla configurazione compose.yaml, queste modifiche non vengono aggiornate con il comando docker compose restart. È necessario usare il comando docker compose up per riflettere gli aggiornamenti e le modifiche nel file compose.yaml.
   • docker compose ps -a elenca tutti i contenitori, inclusi quelli arrestati.
   • docker compose exec consente di eseguire comandi per rimuovere o impostare variabili di ambiente in un contenitore in esecuzione.

   Per altre informazioni, vedere leinformazioni di riferimento sull'interfaccia della riga di comando di Docker.

Passaggi successivi