Traduzione 3.0: Lingue

Articolo
09/22/2023

Ottiene il set di lingue attualmente supportate da altre operazioni del traduttore.

URL richiesta

Inviare una richiesta GET a:

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

VedereRete virtuale Supporto per il servizio Translator selezionato rete e configurazione dell'endpoint privato e supporto.

Parametri della richiesta

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

Parametri di query	Descrizione
api-version	Parametro obbligatorio Versione dell'API richiesta dal client. Il valore deve essere `3.0`.
ambito	Parametro facoltativo. Elenco di nomi delimitato da virgole che definisce il gruppo di lingue da restituire. I nomi di gruppo consentiti sono: `translation`, `transliteration`e `dictionary`. Se non viene specificato un ambito, vengono restituiti tutti i gruppi come se venisse passato `scope=translation,transliteration,dictionary`.

Vederecorpo della risposta.

Le intestazioni della richiesta sono le seguenti:

Intestazioni Descrizione

Accept-Language Intestazione richiesta facoltativa.

Lingua da usare per le stringhe dell'interfaccia utente. Alcuni campi nella risposta sono nomi di lingue o di aree. Usare questo parametro per definire la lingua in cui verranno restituiti tali nomi. La lingua viene specificata fornendo un tag di lingua BCP 47 in formato corretto. Usare ad esempio il valore fr per richiedere i nomi in francese oppure zh-Hant per richiedere i nomi in cinese tradizionale.
I nomi vengono forniti nella lingua inglese quando una lingua di destinazione non è specificata o quando la localizzazione non è disponibile.

X-ClientTraceId Intestazione richiesta facoltativa.
GUID generato dal client che identifica in modo univoco la richiesta.

Intestazioni	Descrizione
Accept-Language	Intestazione richiesta facoltativa. Lingua da usare per le stringhe dell'interfaccia utente. Alcuni campi nella risposta sono nomi di lingue o di aree. Usare questo parametro per definire la lingua in cui verranno restituiti tali nomi. La lingua viene specificata fornendo un tag di lingua BCP 47 in formato corretto. Usare ad esempio il valore `fr` per richiedere i nomi in francese oppure `zh-Hant` per richiedere i nomi in cinese tradizionale. I nomi vengono forniti nella lingua inglese quando una lingua di destinazione non è specificata o quando la localizzazione non è disponibile.
X-ClientTraceId	Intestazione richiesta facoltativa. GUID generato dal client che identifica in modo univoco la richiesta.

Per recuperare le risorse di lingua non è necessaria l'autenticazione.

Corpo della risposta

Un client usa il parametro di query scope per definire i gruppi di lingue a cui è interessato.

scope=translation fornisce le lingue supportate per la traduzione del testo da una lingua a un'altra.
scope=transliteration fornisce le funzionalità per la conversione del testo in una lingua da un alfabeto a un altro.
scope=dictionary fornisce le coppie di lingue per cui le operazioni Dictionary restituiscono dati.

Un client può recuperare diversi gruppi contemporaneamente specificando un elenco di nomi delimitato da virgole. scope=translation,transliteration,dictionary, ad esempio, restituirà le lingue supportate per tutti i gruppi.

Una risposta corretta è un oggetto JSON con una proprietà per ogni gruppo richiesto:

{
    "translation": {
        //... set of languages supported to translate text (scope=translation)
    },
    "transliteration": {
        //... set of languages supported to convert between scripts (scope=transliteration)
    },
    "dictionary": {
        //... set of languages supported for alternative translations and examples (scope=dictionary)
    }
}

Di seguito è riportato il valore di ogni proprietà.

Proprietàtranslation

Il valore di translation è un dizionario di coppie (chiave, valore). Ogni chiave è un tag di lingua BCP 47. Una chiave identifica una lingua da o verso la quale può essere tradotto il testo. Il valore associato alla chiave è un oggetto JSON con le proprietà che descrivono la lingua.
- name: nome visualizzato della lingua nelle impostazioni locali richieste tramite l'intestazione Accept-Language.
- nativeName: nome visualizzato della lingua nelle relative impostazioni locali native.
- dir: direzionalità, che è rtl per le lingue da destra a sinistra e ltr per le lingue da sinistra a destra.
Di seguito è riportato un esempio:
```
{
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}
```
Proprietàtransliteration

Il valore di transliteration è un dizionario di coppie (chiave, valore). Ogni chiave è un tag di lingua BCP 47. Una chiave identifica un lingua per cui il testo può essere convertito da un alfabeto a un altro. Il valore associato alla chiave è un oggetto JSON con le proprietà che descrivono la lingua e gli alfabeti supportati.
- name: nome visualizzato della lingua nelle impostazioni locali richieste tramite l'intestazione Accept-Language.
- nativeName: nome visualizzato della lingua nelle relative impostazioni locali native.
- scripts: elenco degli alfabeti da cui eseguire la conversione. Ogni elemento dell'elenco di scripts contiene le proprietà seguenti.
  - code: codice che identifica l'alfabeto.
  - name: nome visualizzato dell'alfabeto nelle impostazioni locali richieste tramite l'intestazione Accept-Language.
  - nativeName: nome visualizzato della lingua nelle relative impostazioni locali native.
  - dir: direzionalità, che è rtl per le lingue da destra a sinistra e ltr per le lingue da sinistra a destra.
  - toScripts: elenco degli alfabeti in cui è possibile convertire il testo. Ogni elemento dell'elenco di toScripts contiene le proprietà code, name, nativeName e dir descritte in precedenza.
Di seguito è riportato un esempio:
```
{
  "transliteration": {
    ...
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "scripts": [
        {
          "code": "Jpan",
          "name": "Japanese",
          "nativeName": "日本語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr"
            }
          ]
        },
        {
          "code": "Latn",
          "name": "Latin",
          "nativeName": "ラテン語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Jpan",
              "name": "Japanese",
              "nativeName": "日本語",
              "dir": "ltr"
            }
          ]
        }
      ]
    },
    ...
  }
}
```
Proprietàdictionary

Il valore di dictionary è un dizionario di coppie (chiave, valore). Ogni chiave è un tag di lingua BCP 47. La chiave identifica la lingua per cui sono disponibili traduzioni inverse e traduzioni alternative. Il valore è un oggetto JSON che descrive la lingua di origine e le lingue di destinazione con le traduzioni disponibili.
- name: nome visualizzato della lingua di origine nelle impostazioni locali richieste tramite l'intestazione Accept-Language.
- nativeName: nome visualizzato della lingua nelle relative impostazioni locali native.
- dir: direzionalità, che è rtl per le lingue da destra a sinistra e ltr per le lingue da sinistra a destra.
- translations: elenco delle lingue con traduzioni alternative ed esempi della query espressa nella lingua di origine. Ogni elemento dell'elenco di translations contiene le proprietà seguenti.
  - name: nome visualizzato della lingua di destinazione nelle impostazioni locali richieste tramite l'intestazione Accept-Language.
  - nativeName: nome visualizzato della lingua di destinazione nelle relative impostazioni locali native.
  - dir: direzionalità, che è rtl per le lingue da destra a sinistra e ltr per le lingue da sinistra a destra.
  - code: codice di lingua che identifica la lingua di destinazione.
Di seguito è riportato un esempio:
```
"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},
```

La struttura dell'oggetto response non cambia senza una modifica nella versione dell'API. Per la stessa versione dell'API, l'elenco delle lingue disponibili può variare nel tempo perché l'elenco delle lingue supportate dai servizi di Microsoft Translator viene continuamente esteso.

L'elenco delle lingue supportate non cambia di frequente. Per risparmiare larghezza di banda e migliorare la velocità di risposta, per un'applicazione client può essere opportuno memorizzare nella cache le risorse di lingua e il tag di entità corrispondente (ETag). L'applicazione client potrà quindi eseguire periodicamente query sul servizio, ad esempio ogni 24 ore, per recuperare il set di lingue supportate più recente. Il passaggio del valore corrente ETag in un If-None-Match campo di intestazione consente al servizio di ottimizzare la risposta. Se la risorsa non è stata modificata, il servizio restituisce il codice di stato 304 e un corpo di risposta vuoto.

Intestazioni di risposta

Intestazioni	Descrizione
ETag	Valore corrente del tag di entità per i gruppi di lingue supportate richiesti. Per rendere più efficienti le richieste successive, il client può inviare il valore di `ETag` in un campo dell'intestazione `If-None-Match`.
X-RequestId	Valore generato dal servizio per identificare la richiesta. Viene usato a scopo di risoluzione dei problemi.

Codici di stato della risposta

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

Codice di stato	Descrizione
200	Operazione completata.
304	La risorsa non è stata modificata dopo la versione specificata dalle intestazioni `If-None-Match`della richiesta .
400	Uno dei parametri di query non è presente o non è valido. Prima di riprovare, correggere i parametri della richiesta.
429	Il server ha rifiutato la richiesta perché il client ha superato i limiti delle richieste.
500	Si è verificato un errore imprevisto. Se l'errore persiste, segnalarlo specificando data e ora dell'errore, identificatore della richiesta dall'intestazione della riposta `X-RequestId` e identificatore del client dall'intestazione della richiesta `X-ClientTraceId`.
503	Il server è temporaneamente non disponibile. ripetere la richiesta. Se l'errore persiste, segnalarlo specificando data e ora dell'errore, identificatore della richiesta dall'intestazione della riposta `X-RequestId` e identificatore del client dall'intestazione della richiesta `X-ClientTraceId`.

Se si verifica un errore, la richiesta restituisce anche 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.

Esempio

L'esempio seguente mostra come recuperare le lingue supportate per la traduzione del testo.

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"

Share via