Contenitore: Tradurre testo

Articolo
09/01/2024

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

Query parameter (Parametro di query)	Descrizione	Condizione
api-version	Versione dell'API richiesta dal client. Il valore deve essere `3.0`.	Parametro obbligatorio
da	Specifica la lingua del testo di input.	Parametro obbligatorio
to	Specifica la lingua del testo di output. Ad esempio, usare `to=de` per la traduzione in tedesco. È possibile tradurre in più lingue contemporaneamente ripetendo il parametro nella stringa di query. Ad esempio, usare `to=de&to=it` per la traduzione in tedesco e in italiano.	Parametro obbligatorio

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

Parametri facoltativi

Query parameter (Parametro di query)	Descrizione
textType	Parametro facoltativo. Definisce se il testo tradotto è testo normale o testo HTML. Qualsiasi codice HTML deve essere un elemento completo ben formato. I valori possibili sono: `plain` (impostazione predefinita) o `html`.
includeSentenceLength	Parametro facoltativo. Specifica se includere delimitatori di frase per il testo di input e il testo tradotto. I valori possibili sono: `true` o `false` (impostazione predefinita).

Intestazioni delle richieste

Intestazioni	Descrizione	Condizione
Intestazioni di autenticazione	Vedere le opzioni disponibili per l'autenticazione.	Intestazione richiesta obbligatoria
Content-Type	Specifica il tipo di contenuto del payload. Il valore accettato è `application/json; charset=UTF-8`.	Intestazione richiesta obbligatoria
Content-Length	Lunghezza del corpo della richiesta.	Facoltativo
X-ClientTraceId	GUID generato dal client che identifica in modo univoco la richiesta. È possibile omettere questa intestazione se nella stringa della query si include l'ID traccia usando un parametro di query denominato `ClientTraceId`.	Facoltativo

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

Intestazioni	Descrizione
X-RequestId	Valore generato dal servizio per identificare la richiesta e usata per la risoluzione dei problemi.
X-MT-System	Specifica il tipo di sistema utilizzato per la traduzione per ogni lingua "to" richiesta per la traduzione. Il valore è un elenco di stringhe delimitate da virgole. Ogni stringa indica un tipo: ▪ Custom - Request include un sistema personalizzato e almeno un sistema personalizzato è stato usato durante la traduzione. ▪ Team - Tutte le altre richieste

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

Nota

Ogni esempio viene eseguito nell'oggetto localhost specificato con il docker run comando .
Mentre il contenitore è in esecuzione, localhost punta al contenitore stesso.
Non è necessario usare localhost:5000. È possibile usare qualsiasi porta non già in uso nell'ambiente host.

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?'}]"

Nota

Se si tenta di eseguire la richiesta cURL POST prima che il contenitore sia pronto, si otterrà una risposta Il servizio non è temporaneamente disponibile. Attendere che il contenitore sia pronto, quindi riprovare.

Tradurre testo con l'API Swagger

Inglese ↔ tedesco

Passare alla pagina Swagger: http://localhost:5000/swagger/index.html
Selezionare POST /translate
Selezionare Prova
Immettere il parametro Da come en
Immettere il parametro A come de
Immettere il parametro api-version come 3.0
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.

Operazione	Dimensione massima dell'elemento della matrice	Numero massimo di elementi di matrice	Dimensioni massime richieste (caratteri)
tradurre	10,000	100	50,000

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.

Operazione	Query di richiesta	Tipo di documento	Supporto dei contenitori
• Traduzione di testo • Traduzione di documenti	`from` specificato.	Documenti di Office	None
• Traduzione di testo • Traduzione di documenti	`from` non specificato. Richiede il rilevamento automatico della lingua per determinare la lingua di origine.	Documenti di Office	✔️ Analisi del testo: contenitore lingua
• Traduzione di testo • Traduzione di documenti	`from` specificato.	Documenti PDF analizzati	✔️ Contenitore Vision:read
• Traduzione di testo • Traduzione di documenti	`from` non specificato che richiede il rilevamento automatico della lingua per determinare la lingua di origine.	Documenti PDF analizzati	✔️ Analisi del testo: contenitore lingua ✔️ Contenitore Vision:read

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:

Contenitore	Posizione dell'immagine	Note
Traduttore: Traduzione testuale	`mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`	È possibile visualizzare l'elenco completo dei tag di versione Traduzione testo Servizi di Azure AI in MCR.
Traduttore: Traduzione documenti	TODO	TODO
Analisi del testo: lingua	`mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest`	È possibile visualizzare l'elenco completo dei tag di versione della lingua di analisi del testo dei Servizi di Azure AI in MCR.
Visione: lettura	`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`	È possibile visualizzare l'elenco completo dei tag di versione di lettura Visione artificiale Servizi di Azure AI`OCR` in MCR.

Creare l'applicazione

Usando l'editor o l'IDE preferito, creare una nuova directory per l'app denominata container-environment o un nome di propria scelta.
Creare un nuovo file YAML denominato compose.yaml. Entrambe le estensioni .yml o yaml possono essere usate per il file compose.
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
Il nome di primo livello (azure-ai-translator, azure-ai-language, azure-ai-read) è il parametro specificato.

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}

Aprire un terminale passare alla cartella container-environment e avviare i contenitori con il comando docker-compose seguente:
```
docker compose up
```
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

Altre informazioni sulla traduzione testuale

Condividi tramite