Share via

Contenitore: Tradurre testo

  • Articolo

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

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 Vederele 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 10.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 Traduttore di Intelligenza artificiale di Azure (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

  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 10.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 conversione Traduttore.

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

Usare docker compose: Traduttore 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 per avviare l'applicazione docker compose up contenitore e il docker compose down comando 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 sull'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 di intelligenza artificiale di Azure nell'account Azure.

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

Vision:read container ✔️
Immagini e tag del contenitore

Le immagini del contenitore dei servizi di intelligenza artificiale di Azure sono disponibili nel catalogo Registro artefatti Microsoft. La tabella seguente elenca il percorso completo dell'immagine per la traduzione di testo e documento:

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 testuale dei servizi di intelligenza artificiale di Azure in MCR.
Traduttore: Traduzione di documenti TODO TODO
Analisi del testo: lingua mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest È possibile visualizzare l'elenco completo dei servizi di intelligenza artificiale di Azure Analisi del testo tag di versione del linguaggio in MCR.
Visione: lettura mcr.microsoft.com/azure-cognitive-services/vision/read:latest È possibile visualizzare l'elenco completo dei servizi di intelligenza artificiale di Azure Visione artificiale Leggere OCR i tag di versione in MCR.

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 compose file.

  3. Copiare e incollare l'esempio di codice YAML seguente nel compose.yaml file. Sostituire {TRANSLATOR_KEY} e {TRANSLATOR_ENDPOINT_URI} con i valori della chiave e dell'endpoint dell'istanza di portale di Azure Traduttore. 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 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 container-environment cartella e avviare i contenitori con il comando seguente docker-compose :

    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} rimuove i contenitori sospesi.
    • docker compose restart riavvia tutti i contenitori arrestati ed in esecuzione con tutte le modifiche precedenti intatte. Se si apportano modifiche alla compose.yaml configurazione, queste modifiche non vengono aggiornate con il docker compose restart comando . È necessario usare il docker compose up comando per riflettere gli aggiornamenti e le modifiche nel compose.yaml file.
    • docker compose ps -a elenca tutti i contenitori, inclusi quelli arrestati.
    • docker compose execconsente di eseguire comandi per scollegare 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