Traduttore 3.0: Lingue

Articolo
09/02/2024

Ottiene il set di lingue attualmente supportate da altre operazioni di Translator.

Richiesta URL

Inviare una richiesta GET a:

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

Per le reti virtuali, usare l'endpoint di dominio personalizzato:

https://<your-custom-domain>.cognitiveservices.azure.com/languages?api-version=3.0

Per altre informazioni, 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 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`.

Vedere corpo della risposta.

Le intestazioni della richiesta sono le seguenti:

Intestazioni Descrizione

Accept-Language Intestazione di 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 ben formato BCP 47. 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 non viene specificata una lingua di destinazione o quando la localizzazione non è disponibile.

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

Intestazioni	Descrizione
Accept-Language	Intestazione di 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 ben formato `BCP` 47. 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 non viene specificata una lingua di destinazione o quando la localizzazione non è disponibile.
X-ClientTraceId	Intestazione di 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 scope parametro di query per definire i gruppi di lingue da elencare.

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 BCP tag di lingua 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 BCP tag di lingua 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 BCP tag di lingua 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 risposta non cambia senza alcuna 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 frequentemente. 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 viene modificata, il servizio restituisce il codice di stato 304 e un corpo della risposta vuoto.

Intestazioni della 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 per la 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	Esito positivo.
304	La risorsa non viene modificata e allineata alla versione specificata dalle intestazioni della `If-None-Match`richiesta .
400	Uno dei parametri di query manca 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	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.

Esempi

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"

Condividi tramite