Traduttore 3.0: Traduci

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 Traduttore servizio 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 il from parametro non è specificato, 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 dal file Personalizzato Traduttore dettagli del progetto 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	Intestazione della richiesta obbligatoria. 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.

Corpo 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, vedereLimiti 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).

ProfanityAction	Azione
NoAction	NoAction è il comportamento predefinito. Il contenuto volgare passa dall'origine alla destinazione. Origine di esempio (giapponese): 彼はジャッカスです。 Traduzione di esempio (inglese): è un jack---.
Deleted	Le parole volgari vengono rimosse dall'output senza sostituzione. Origine di esempio (giapponese): 彼はジャッカスです。 Traduzione di esempio (inglese): è un**
Marked	Un marcatore sostituisce la parola contrassegnata nell'output. L'indicatore dipende dal parametro ProfanityMarker. Per ProfanityMarker=Asterisk, le parole volgari vengono sostituite con ***: Origine di esempio (giapponese): 彼はジャッカスです。 Traduzione di esempio (inglese): è un \\\*. Per ProfanityMarker=Tag, le parole volgari sono racchiuse tra tag <XML profanity> e </profanity>: Origine di esempio (giapponese): 彼はジャッカスです。 Traduzione di esempio (inglese): è un <jack volgare>---</volgarità>.

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 sono disponibili informazioni di allineamento, l'elemento Alignment è 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 la guida introduttiva di Traduttore