Condividi tramite

Traduttore 3.0: Tradurre

  • Articolo

Traduce il testo.

Richiesta URL

Inviare una richiesta POST a:

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0

Vedere Rete virtuale Supporto per il servizio Translator selezionato per la configurazione e il supporto di endpoint privati e di rete.

Parametri della richiesta

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

Parametri obbligatori

Query parameter (Parametro di query) Descrizione
api-version Parametro obbligatorio.
Versione dell'API richiesta dal client. Il valore deve essere 3.0.
to Parametro obbligatorio.
Specifica la lingua del testo di output. La lingua di destinazione deve essere una delle lingue supportate incluse nell'ambito translation. 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.

Parametri facoltativi

Query parameter (Parametro di query) Descrizione
da Parametro facoltativo.
Specifica la lingua del testo di input. Trovare quali lingue sono disponibili per la traduzione eseguendo una ricerca tra le lingue supportate con l'ambito translation. Se non si specifica il parametro from, viene applicato il rilevamento automatico della lingua per determinare la lingua di origine.

È necessario usare il from parametro anziché autodetection quando si usa la funzionalità del dizionario dinamico. Nota: la funzionalità del dizionario dinamico fa distinzione tra maiuscole e minuscole.
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.
category Parametro facoltativo.
Stringa che specifica la categoria (dominio) della traduzione. Questo parametro viene usato per ottenere le traduzioni da un sistema personalizzato compilato con Custom Translator. Per usare il sistema personalizzato distribuito, aggiungere l'ID categoria dai dettagli del progetto Custom Translator al parametro category. Il valore predefinito è: general.
profanityAction Parametro facoltativo.
Specifica come deve essere trattato il contenuto volgare nelle traduzioni. I valori possibili sono: NoAction (impostazione predefinita), Markedo Deleted. Per informazioni sui metodi di gestione del contenuto volgare, vedere Gestione del contenuto volgare.
profanityMarker Parametro facoltativo.
Specifica come deve essere contrassegnato il contenuto volgare nelle traduzioni. I valori possibili sono: Asterisk (impostazione predefinita) o Tag. Per informazioni sui metodi di gestione del contenuto volgare, vedere Gestione del contenuto volgare.
includeAlignment Parametro facoltativo.
Specifica se includere la proiezione dell'allineamento dal testo di origine al testo tradotto. I valori possibili sono: true o false (impostazione predefinita).
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).
suggestedFrom Parametro facoltativo.
Specifica una lingua di fallback se non è possibile identificare la lingua del testo di input. La lingua autodetection viene applicata quando il from parametro viene omesso. Se il rilevamento non riesce, viene presupposta la suggestedFrom lingua.
fromScript Parametro facoltativo.
Specifica l'alfabeto del testo di input.
toScript Parametro facoltativo.
Specifica l'alfabeto del testo tradotto.
allowFallback Parametro facoltativo.
Specifica che il servizio può eseguire il fallback a un sistema generale quando non esiste un sistema personalizzato. I valori possibili sono: true (impostazione predefinita) o false.

allowFallback=false specifica che la traduzione deve usare solo sistemi sottoposti a training per il valore di category definito dalla richiesta. Se una traduzione dalla lingua X alla lingua Y richiede il concatenamento attraverso una lingua pivot E, tutti i sistemi nella catena (X → E e E → Y) devono essere personalizzati e avere la stessa categoria. Se non viene trovato alcun sistema con la categoria specifica, la richiesta restituisce un codice di stato 400. allowFallback=true specifica che il servizio può eseguire il fallback a un sistema generale quando non esiste un sistema personalizzato.

Le intestazioni della richiesta includono:

Intestazioni Descrizione
Intestazioni di autenticazione Intestazione della richiesta obbligatoria.
Vedere le opzioni disponibili per l'autenticazione.
Content-Type Intestazione della richiesta obbligatoria.
Specifica il tipo di contenuto del payload.
Il valore accettato è application/json; charset=UTF-8.
Content-Length Facoltativo.
Lunghezza del corpo della richiesta.
X-ClientTraceId Facoltativo.
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.

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."}
]

Per informazioni sui limiti di caratteri e matrici, vedere Limiti delle richieste.

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:

  • detectedLanguage: oggetto che descrive la lingua rilevata tramite le proprietà seguenti:

    • language: stringa che rappresenta il codice della lingua rilevata.

    • score: valore float che indica il livello di attendibilità del risultato. Il punteggio è compreso tra zero e uno e un punteggio basso indica un'attendibilità bassa.

    La detectedLanguage proprietà è presente nell'oggetto risultato solo quando viene richiesta la funzionalità automatica della lingua.

  • 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.

    • transliteration: oggetto che fornisce il testo tradotto nell'alfabeto specificato dal parametro toScript.

      • script: stringa che specifica l'alfabeto di destinazione.

      • text: stringa che fornisce il testo tradotto nell'alfabeto di destinazione.

      L'oggetto transliteration non è incluso se la traslitterazione non viene eseguita.

      • alignment: oggetto con una proprietà di stringa singola denominata proj, che esegue il mapping del testo di input con quello tradotto. Le informazioni di allineamento sono disponibili solo quando il parametro della richiesta includeAlignment è true. L'allineamento viene restituito come un valore di stringa nel formato seguente: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. I due punti separano l'indice iniziale e finale, il trattino separa le lingue e uno spazio separa le parole. Una parola può essere allineata con zero, una o più parole nell'altra lingua e le parole allineate possono essere non contigue. Quando non sono disponibili informazioni di allineamento, l'elemento di allineamento è vuoto. Vedere Ottenere informazioni sull'allineamento per un esempio e le restrizioni.

    • 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 fosse arabo scritto in alfabeto latino, sourceText.text lo stesso testo arabo convertito nello script arabo.

Esempi di risposte JSON sono disponibili nella sezione degli esempi .

Intestazioni della risposta

Intestazioni Descrizione
X-requestid Valore generato dal servizio per identificare la richiesta 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
Utilizzo a consumo X Specifica il consumo (il numero di caratteri per cui viene addebitato l'utente) per la richiesta di processo di traduzione. Ad esempio, se la parola "Hello" viene tradotta dall'inglese (en) al francese (fr), questo campo restituisce il valore 5.

Codici di stato della risposta

Di seguito sono riportati i possibili codici di stato HTTP restituiti da una richiesta.

Codice di stato Descrizione
200 Esito positivo.
400 Uno dei parametri di query manca o non è valido. Prima di riprovare, correggere i parametri della richiesta.
401 Impossibile autenticare la richiesta. Verificare che le credenziali siano state specificate e che siano valide.
403 La richiesta non è autorizzata. Controllare il messaggio di errore per i dettagli. Questo codice di stato indica spesso che sono state usate tutte le traduzioni gratuite fornite con una sottoscrizione di valutazione.
408 Impossibile soddisfare la richiesta perché manca una risorsa. Controllare il messaggio di errore per i dettagli. Quando la richiesta include una categoria personalizzata, questo codice di stato spesso indica che il sistema di traduzione personalizzato non è ancora disponibile per gestire le richieste. La richiesta deve essere ritentata dopo un periodo di attesa (ad esempio, 1 minuto).
429 Il server ha rifiutato la richiesta perché il client ha superato i limiti delle richieste.
500 Errore imprevisto. Se l'errore persiste, segnalarlo con: data e ora dell'errore, identificatore della richiesta dall'intestazione di risposta X-RequestId e identificatore client dall'intestazione della richiesta X-ClientTraceId.
503 Il server è temporaneamente non disponibile. ripetere la richiesta. Se l'errore persiste, segnalarlo con: data e ora dell'errore, identificatore della richiesta dall'intestazione di risposta X-RequestId e identificatore client dall'intestazione della richiesta X-ClientTraceId.

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

Tradurre un singolo input

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

curl -X POST "https://api.cognitive.microsofttranslator.com/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.

Tradurre un singolo input con la lingua autodetection

Questo esempio mostra come tradurre una singola frase dall'inglese al cinese semplificato. La richiesta non specifica la lingua di input. Viene invece usata l'opzione Autodetection della lingua di origine.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&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 è:

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

La risposta è simile a quella dell'esempio precedente. Poiché è stata richiesta la funzione automatica della lingua, la risposta include anche informazioni sulla lingua rilevata per il testo di input. L'autodetection della lingua funziona meglio con testo di input più lungo.

Tradurre con traslitterazione

È possibile estendere l'esempio precedente aggiungendo la traslitterazione. La richiesta seguente richiede una traduzione in cinese scritta in caratteri dell'alfabeto latino.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -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 è:

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

Il risultato della traduzione include ora una proprietà transliteration, che fornisce il testo tradotto usando caratteri dell'alfabeto latino.

Tradurre più parti di testo

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

curl -X POST "https://api.cognitive.microsofttranslator.com/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 "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

Gestire contenuto volgare

In genere, il servizio Traduttore mantiene il contenuto volgare presente nell'origine nella traduzione. Il grado di volgarità e contesto che rende le parole volgari differiscono tra le culture e, di conseguenza, il grado di volgarità nella lingua di destinazione può essere amplificato o ridotto.

Se si vuole evitare la presenza di contenuto volgare nella traduzione, indipendentemente dalla presenza di contenuto volgare nel testo di origine, è possibile usare l'opzione di filtro per il contenuto volgare. L'opzione consente di scegliere se si vuole visualizzare il contenuto volgare eliminato, contrassegnato con tag appropriati (offrendo la possibilità di aggiungere la propria post-elaborazione) o senza alcuna azione eseguita. I valori accettati di ProfanityAction sono Deleted, Markede NoAction (impostazione predefinita).

Valore VolgarityAction accettato Valore ProfanityMarker Azione Esempio: origine - spagnolo Esempio: destinazione - inglese
NoAction Valore predefinito. Equivale a non impostare l'opzione. Il contenuto volgare passa dall'origine alla destinazione. Que coche de<insert-profane-word> What a <insert-profane-word> car
Marked Asterisco Gli asterischi sostituiscono le parole volgari (impostazione predefinita). Que coche de<insert-profane-word> What a *** car
Marked Tag Le parole volgari sono racchiuse tra i tag XML <profanity>...</profanity>. Que coche de<insert-profane-word> What a <profanity><insert-profane-word></profanity> car
Eliminata Le parole volgari vengono rimosse dall'output senza sostituzione. Que coche de<insert-profane-word> What a car

Negli esempi precedenti, <insert-profane-word> è un segnaposto per le parole volgari.

Ad esempio:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Questa richiesta restituisce:

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

Eseguire il confronto con:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

L'ultima richiesta restituisce:

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

Tradurre il contenuto che include markup

È 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 "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

Ottenere informazioni sull'allineamento

L'allineamento viene restituito come un valore di stringa nel formato seguente per ogni parola dell'origine. Le informazioni per ogni parola sono separate da uno spazio, incluse le lingue non separate da spazi (script), ad esempio il cinese:

[[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]] *

Stringa di allineamento di esempio: "0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21".

In altre parole, i due punti separano l'indice iniziale e finale, il trattino separa le lingue e uno spazio separa le parole. Una parola può essere allineata con zero, una o più parole nell'altra lingua e le parole allineate possono essere non contigue. Quando non è disponibile alcuna informazione di allineamento, l'elemento Allineamento è vuoto. In questo caso il metodo non restituisce alcun errore.

Per ricevere informazioni sull'allineamento, specificare includeAlignment=true nella stringa di query.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

La risposta è:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

Le informazioni sull'allineamento iniziano con 0:2-0:1, vale a dire che i primi tre caratteri nel testo di origine (The) sono associati ai primi due caratteri nel testo tradotto (La).

Limiti

Ottenere informazioni sull'allineamento è una funzionalità sperimentale abilitata per la ricerca di prototipi ed esperienze con potenziali mapping di frasi. Ecco alcune delle restrizioni rilevanti in cui gli allineamenti non sono supportati:

  • L'allineamento non è disponibile per il testo in formato HTML, ovvero textType=html
  • L'allineamento viene restituito solo per un subset delle coppie di lingue:
    • Inglese da/verso qualsiasi altra lingua, ad eccezione del cinese tradizionale, del Cantonse (tradizionale) o serbo (cirillico)
    • dal giapponese al coreano o dal coreano al giapponese
    • dal giapponese al cinese semplificato e cinese semplificato al giapponese
    • dal cinese semplificato al cinese tradizionale e cinese tradizionale al cinese semplificato
  • Non si allinea se la frase è una traduzione in scatola. Un esempio di traduzione canned è This is a test, I love youe altre frasi ad alta frequenza
  • L'allineamento non è disponibile quando si applica uno degli approcci per impedire la traduzione, come descritto qui

Ottenere delimitatori di frase

Per ricevere informazioni sulla lunghezza della frase nel testo di origine e nel testo tradotto, specificare includeSentenceLength=true nella stringa di query.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

La risposta è:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

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. Nota: la funzionalità del dizionario dinamico fa distinzione tra maiuscole e minuscole.

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 "https://api.cognitive.microsofttranslator.com/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\">wordomatic</mstrans:dictionary> is a dictionary entry.'}]"

Il risultato è:

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

Questa funzionalità del dizionario dinamico 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 è possibile creare dati di training che mostrano il lavoro o la frase nel contesto, si ottengono risultati migliori. Altre informazioni su Custom Translator.

Passaggi successivi

Provare l'avvio rapido di Translator