Translator 3.0: Diller

Makale
07/03/2024

Translator'ın diğer işlemleri tarafından desteklenen dil kümesini alır.

İstek URL’si

Şuraya bir GET isteği gönderin:

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

Bkz. Sanal Ağ Translator hizmeti için seçilen ağ ve özel uç nokta yapılandırması ve desteği için Destek.

İstek parametreleri

Sorgu dizesinde geçirilen istek parametreleri şunlardır:

Sorgu parametreleri	Açıklama
api-sürümü	Gerekli parametre İstemci tarafından istenen API sürümü. Değer olmalıdır `3.0`.
kapsam	İsteğe bağlı parametre. Döndürülecek dil grubunu tanımlayan adların virgülle ayrılmış listesi. İzin verilen grup adları şunlardır: `translation`, `transliteration`ve `dictionary`. Kapsam verilmezse, tüm gruplar döndürülür ve bu da geçirilmesiyle `scope=translation,transliteration,dictionary`eşdeğerdir.

Bkz. yanıt gövdesi.

İstek üst bilgileri şunlardır:

Üst Bilgiler Açıklama

Accept-Language İsteğe bağlı istek üst bilgisi.

Kullanıcı arabirimi dizelerinde kullanılacak dil. Yanıttaki alanlardan bazıları dillerin adları veya bölgelerin adlarıdır. Bu adların döndürüldiği dili tanımlamak için bu parametreyi kullanın. Dil, iyi biçimlendirilmiş bir BCP 47 dil etiketi sağlanarak belirtilir. Örneğin, Fransızca ad istemek için değerini fr veya Geleneksel Çince'de ad istemek için değerini zh-Hant kullanın.
Hedef dil belirtilmediğinde veya yerelleştirme kullanılamadığında, adlar İngilizce dilinde sağlanır.

X-ClientTraceId İsteğe bağlı istek üst bilgisi.
İsteği benzersiz olarak tanımlamak için istemci tarafından oluşturulan GUID.

Üst Bilgiler	Açıklama
Accept-Language	İsteğe bağlı istek üst bilgisi. Kullanıcı arabirimi dizelerinde kullanılacak dil. Yanıttaki alanlardan bazıları dillerin adları veya bölgelerin adlarıdır. Bu adların döndürüldiği dili tanımlamak için bu parametreyi kullanın. Dil, iyi biçimlendirilmiş bir BCP 47 dil etiketi sağlanarak belirtilir. Örneğin, Fransızca ad istemek için değerini `fr` veya Geleneksel Çince'de ad istemek için değerini `zh-Hant` kullanın. Hedef dil belirtilmediğinde veya yerelleştirme kullanılamadığında, adlar İngilizce dilinde sağlanır.
X-ClientTraceId	İsteğe bağlı istek üst bilgisi. İsteği benzersiz olarak tanımlamak için istemci tarafından oluşturulan GUID.

Dil kaynaklarını almak için kimlik doğrulaması gerekmez.

Yanıt gövdesi

İstemci, hangi dil gruplarının ilgilendiğini tanımlamak için sorgu parametresini kullanır scope .

scope=translation metinleri bir dilden başka bir dile çevirmek için desteklenen diller sağlar;
scope=transliteration bir dildeki metni bir betikten başka bir betike dönüştürme özellikleri sağlar;
scope=dictionary , işlemlerin veri döndüreceği Dictionary dil çiftleri sağlar.

bir istemci, virgülle ayrılmış bir ad listesi belirterek birkaç grubu aynı anda alabilir. Örneğin, scope=translation,transliteration,dictionary tüm gruplar için desteklenen dilleri döndürür.

Başarılı bir yanıt, istenen her grup için bir özelliği olan bir JSON nesnesidir:

{
    "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)
    }
}

Her özelliğin değeri aşağıdaki gibidir.

translation mülk

özelliğinin translation değeri (anahtar, değer) çiftlerinin sözlüğüdür. Her anahtar bir BCP 47 dil etiketidir. Anahtar, metnin çevrilebileceği veya çevrilebileceği bir dili tanımlar. Anahtarla ilişkili değer, dili açıklayan özelliklere sahip bir JSON nesnesidir:
- name: Üst bilgi aracılığıyla Accept-Language istenen yerel ayarda dilin görünen adı.
- nativeName: Bu dilin yerel ayarında dilin adını görüntüleyin.
- dir: Sağdan sola veya ltr soldan sağa diller için olan rtl yön.
Örnek olarak:
```
{
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}
```
transliteration mülk

özelliğinin transliteration değeri (anahtar, değer) çiftlerinin sözlüğüdür. Her anahtar bir BCP 47 dil etiketidir. Anahtar, metnin bir betikten başka bir betike dönüştürülebileceği bir dili tanımlar. Anahtarla ilişkili değer, dili ve desteklenen betiklerini açıklayan özelliklere sahip bir JSON nesnesidir:
- name: Üst bilgi aracılığıyla Accept-Language istenen yerel ayarda dilin görünen adı.
- nativeName: Bu dilin yerel ayarında dilin adını görüntüleyin.
- scripts: Dönüştürülecek betiklerin listesi. Listenin her öğesinin scripts özellikleri vardır:
  - code: Betiği tanımlayan kod.
  - name: Üst bilgi aracılığıyla Accept-Language istenen yerel ayarda betiğin görünen adı.
  - nativeName: Dilin yerel ayarında dilin adını görüntüler.
  - dir: Sağdan sola veya ltr soldan sağa diller için olan rtl yön.
  - toScripts: Metni dönüştürmek için kullanılabilecek betiklerin listesi. Listenin toScripts her öğesi, daha önce açıklandığı gibi , name, nativeNameve dir özelliklerine codesahiptir.
Örnek olarak:
```
{
  "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"
            }
          ]
        }
      ]
    },
    ...
  }
}
```
dictionary mülk

özelliğinin dictionary değeri (anahtar, değer) çiftlerinin sözlüğüdür. Her anahtar bir BCP 47 dil etiketidir. Anahtar, alternatif çevirilerin ve arka çevirilerin kullanılabildiği bir dili tanımlar. Değer, kaynak dili ve kullanılabilir çevirileri olan hedef dilleri açıklayan bir JSON nesnesidir:
- name: Üst bilgi aracılığıyla Accept-Language istenen yerel ayarda kaynak dilin görünen adı.
- nativeName: Bu dilin yerel ayarında dilin adını görüntüleyin.
- dir: Sağdan sola veya ltr soldan sağa diller için olan rtl yön.
- translations: Alternatif çevirileri olan dillerin listesi ve kaynak dilde ifade edilen sorgu örnekleri. Listenin her öğesinin translations özellikleri vardır:
  - name: Üst bilgi aracılığıyla Accept-Language istenen yerel ayarda hedef dilin görünen adı.
  - nativeName: Hedef dil için yerel yerel ayarda hedef dilin adını görüntüleyin.
  - dir: Sağdan sola veya ltr soldan sağa diller için olan rtl yön.
  - code: Hedef dili tanımlayan dil kodu.
Örnek olarak:
```
"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},
```

API sürümünde değişiklik yapılmadan yanıt nesnesinin yapısı değişmez. API'nin aynı sürümü için kullanılabilir diller listesi zaman içinde değişebilir çünkü Microsoft Çeviri hizmetleri tarafından desteklenen diller listesini sürekli genişletir.

Desteklenen diller listesi sık sık değişmez. Ağ bant genişliğinden tasarruf etmek ve yanıt hızını artırmak için istemci uygulaması dil kaynaklarını ve karşılık gelen varlık etiketini (ETag) önbelleğe almayı göz önünde bulundurmalıdır. Ardından istemci uygulaması, desteklenen en son dil kümesini getirmek için hizmeti düzenli aralıklarla sorgulayabilir (örneğin, 24 saatte bir). Geçerli ETag değerin bir If-None-Match üst bilgi alanına geçirilmesi, hizmetin yanıtı iyileştirmesine olanak tanır. Kaynak değiştirilmediyse, hizmet 304 durum kodunu ve boş bir yanıt gövdesini döndürür.

Yanıt üst bilgileri

Üst Bilgiler	Açıklama
ETag	İstenen desteklenen dil grupları için varlık etiketinin geçerli değeri. Sonraki istekleri daha verimli hale getirmek için, istemci değeri bir `If-None-Match` üst bilgi alanına gönderebilir`ETag`.
X-RequestId	İsteği tanımlamak için hizmet tarafından oluşturulan değer. Sorun giderme amacıyla kullanılır.

Yanıt durum kodları

Bir isteğin döndürdüğü olası HTTP durum kodları aşağıdadır.

Durum Kodu	Açıklama
200	Başarılı.
304	İstek üst bilgileri `If-None-Match`tarafından belirtilen sürümden bu yana kaynak değiştirilmedi.
400	Sorgu parametrelerinden biri eksik veya geçersiz. Yeniden denemeden önce istek parametrelerini düzeltin.
Kategori 429	İstemci istek sınırlarını aştığı için sunucu isteği reddetti.
500	Beklenmeyen bir hata oluştu. Hata devam ederse şunu bildirin: hatanın tarihi ve saati, yanıt üst bilgisinden istek tanımlayıcısı ve istek üst bilgisinden `X-RequestId`istemci tanımlayıcısı `X-ClientTraceId`.
503	Sunucu geçici olarak kullanılamıyor. İsteği yeniden deneyin. Hata devam ederse şunu bildirin: hatanın tarihi ve saati, yanıt üst bilgisinden istek tanımlayıcısı ve istek üst bilgisinden `X-RequestId`istemci tanımlayıcısı `X-ClientTraceId`.

Hata oluşursa, istek bir JSON hata yanıtı da döndürür. Hata kodu, hatayı daha fazla kategorilere ayırmak için 3 basamaklı HTTP durum kodunu ve ardından 3 basamaklı bir sayıyı birleştiren 6 basamaklı bir sayıdır. Yaygın hata kodları v3 Çevirmen başvuru sayfasında bulunabilir.

Örnekler

Aşağıdaki örnekte, metin çevirisi için desteklenen dillerin nasıl alınıyor olduğu gösterilmektedir.

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

Aracılığıyla paylaş