Translator 3.0: Bahasa

Artikel
09/22/2023

Mendapatkan sekumpulan bahasa yang saat ini didukung oleh operasi lain dari Penerjemah.

URL Permintaan

Kirim permintaan GET ke:

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

LihatVirtual Network Dukungan untuk layanan Penerjemah memilih konfigurasi dan dukungan titik akhir privat dan jaringan.

Parameter permintaan

Parameter permintaan yang diteruskan pada string kueri adalah:

Parameter kueri	Deskripsi
versi-api	Parameter yang diperlukan Versi API yang diminta oleh klien. Nilai harus `3.0`.
cakupan	Parameter opsional. Daftar nama yang dipisahkan koma yang menentukan grup bahasa yang dikembalikan. Nama grup yang diizinkan adalah: `translation`, , `transliteration`dan `dictionary`. Jika tidak ada cakupan yang diberikan, semua grup dikembalikan, yang setara dengan meneruskan `scope=translation,transliteration,dictionary`.

Lihatisi respons.

Header permintaan adalah:

Header Deskripsi

Accept-Language Header permintaan opsional.

Bahasa yang digunakan untuk string antarmuka pengguna. Beberapa bidang dalam respons adalah nama bahasa atau nama wilayah. Gunakan parameter ini untuk menentukan bahasa tempat nama-nama ini dikembalikan. Bahasa ini ditentukan dengan menyediakan tag bahasa BCP 47 yang dibentuk dengan baik. Misalnya, gunakan nilai fr untuk meminta nama dalam bahasa Prancis atau gunakan nilai zh-Hant untuk meminta nama dalam bahasa Mandarin Tradisional.
Nama disediakan dalam bahasa Inggris saat bahasa target tidak ditentukan atau saat pelokalan tidak tersedia.

X-ClientTraceId Header permintaan opsional.
GUID yang dihasilkan klien untuk mengidentifikasi permintaan secara unik.

Header	Deskripsi
Accept-Language	Header permintaan opsional. Bahasa yang digunakan untuk string antarmuka pengguna. Beberapa bidang dalam respons adalah nama bahasa atau nama wilayah. Gunakan parameter ini untuk menentukan bahasa tempat nama-nama ini dikembalikan. Bahasa ini ditentukan dengan menyediakan tag bahasa BCP 47 yang dibentuk dengan baik. Misalnya, gunakan nilai `fr` untuk meminta nama dalam bahasa Prancis atau gunakan nilai `zh-Hant` untuk meminta nama dalam bahasa Mandarin Tradisional. Nama disediakan dalam bahasa Inggris saat bahasa target tidak ditentukan atau saat pelokalan tidak tersedia.
X-ClientTraceId	Header permintaan opsional. GUID yang dihasilkan klien untuk mengidentifikasi permintaan secara unik.

Autentikasi tidak diperlukan untuk mendapatkan sumber daya bahasa.

Isi respons

Klien menggunakan parameter kueri scope untuk menentukan grup bahasa mana yang diminatinya.

scope=translation menyediakan bahasa yang didukung untuk menerjemahkan teks dari satu bahasa ke bahasa lain;
scope=transliteration menyediakan kemampuan untuk mengonversi teks dalam satu bahasa dari satu skrip ke skrip lain;
scope=dictionary menyediakan pasangan bahasa tempat Dictionary operasi mengembalikan data.

Klien dapat mengambil beberapa grup secara bersamaan dengan menentukan daftar nama yang dipisahkan koma. Misalnya, scope=translation,transliteration,dictionary akan mengembalikan bahasa yang didukung untuk semua grup.

Respons yang berhasil adalah objek JSON dengan satu properti untuk setiap grup yang diminta:

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

Nilai untuk setiap properti adalah sebagai berikut.

Properti translation.

Nilai properti translation adalah kamus pasangan (kunci, nilai). Setiap kunci adalah tag bahasa BCP 47. Kunci mengidentifikasi bahasa tempat teks dapat diterjemahkan ke atau diterjemahkan dari. Nilai yang terkait dengan kunci adalah objek JSON dengan properti yang menjelaskan bahasa:
- name: Menampilkan nama bahasa di lokal yang diminta melalui header Accept-Language.
- nativeName: Menampilkan nama bahasa dalam bahasa asli lokal untuk bahasa ini.
- dir: Arahan, yaitu rtl untuk bahasa kanan ke kiri atau ltr untuk bahasa kiri ke kanan.
Contohnya adalah:
```
{
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}
```
Properti transliteration

Nilai properti transliteration adalah kamus pasangan (kunci, nilai). Setiap kunci adalah tag bahasa BCP 47. Kunci mengidentifikasi bahasa tempat teks dapat dikonversi dari satu skrip ke skrip lain. Nilai yang terkait dengan kunci adalah objek JSON dengan properti yang menjelaskan bahasa dan skrip yang didukungnya:
- name: Menampilkan nama bahasa di lokal yang diminta melalui header Accept-Language.
- nativeName: Menampilkan nama bahasa dalam bahasa asli lokal untuk bahasa ini.
- scripts: Daftar skrip untuk dikonversi. Setiap elemen dari daftar scripts memiliki properti:
  - code: Kode yang mengidentifikasi skrip.
  - name: Menampilkan skrip di lokal yang diminta melalui header Accept-Language.
  - nativeName: Menampilkan nama bahasa dalam bahasa asli lokal untuk bahasa ini.
  - dir: Arahan, yaitu rtl untuk bahasa kanan ke kiri atau ltr untuk bahasa kiri ke kanan.
  - toScripts: Daftar skrip yang tersedia untuk mengonversi teks. Setiap elemen dari daftar toScripts memiliki properti code, name, nativeName, dan dir sebagaimana yang dijelaskan sebelumnya.
Contohnya adalah:
```
{
  "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"
            }
          ]
        }
      ]
    },
    ...
  }
}
```
Properti dictionary

Nilai properti dictionary adalah kamus pasangan (kunci, nilai). Setiap kunci adalah tag bahasa BCP 47. Kunci mengidentifikasi bahasa tempat terjemahan alternatif dan terjemahan kembali tersedia. Nilainya adalah objek JSON yang menjelaskan bahasa sumber dan bahasa target dengan terjemahan yang tersedia:
- name: Menampilkan nama bahasa sumber di lokal yang diminta melalui header Accept-Language.
- nativeName: Menampilkan nama bahasa dalam bahasa asli lokal untuk bahasa ini.
- dir: Arahan, yaitu rtl untuk bahasa kanan ke kiri atau ltr untuk bahasa kiri ke kanan.
- translations: Daftar bahasa dengan terjemahan dan contoh alteratif untuk kueri yang dinyatakan dalam bahasa sumber. Setiap elemen dari daftar translations memiliki properti:
  - name: Menampilkan nama bahasa target di lokal yang diminta melalui header Accept-Language.
  - nativeName: Menampilkan nama bahasa target dalam bahasa asli lokal untuk bahasa target ini.
  - dir: Arahan, yaitu rtl untuk bahasa kanan ke kiri atau ltr untuk bahasa kiri ke kanan.
  - code: Kode bahasa yang mengidentifikasi bahasa target.
Contohnya adalah:
```
"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},
```

Struktur objek respons tidak berubah tanpa perubahan dalam versi API. Untuk versi API yang sama, daftar bahasa yang tersedia dapat berubah dari waktu ke waktu karena Microsoft Translator terus memperluas daftar bahasa yang didukung oleh layanannya.

Daftar bahasa yang didukung tidak sering berubah. Untuk menyimpan bandwidth jaringan dan meningkatkan responsivitas, aplikasi klien harus mempertimbangkan sumber daya bahasa caching dan tag entitas yang sesuai (ETag). Selanjutnya, aplikasi klien dapat secara berkala (misalnya, setiap 24 jam sekali) meminta layanan untuk mengambil kumpulan bahasa terbaru yang didukung. Meneruskan nilai saat ini ETag di If-None-Match bidang header memungkinkan layanan untuk mengoptimalkan respons. Jika sumber daya belum dimodifikasi, layanan mengembalikan kode status 304 dan isi respons kosong.

Header respons

Header	Deskripsi
ETag	Nilai saat ini dari tag entitas untuk grup yang diminta dari bahasa yang didukung. Untuk membuat permintaan berikutnya lebih efisien, klien dapat mengirim nilai `ETag` di bidang header `If-None-Match`.
X-RequestId	Nilai yang dihasilkan oleh layanan untuk mengidentifikasi permintaan. Nilai ini digunakan untuk tujuan pemecahan masalah.

Kode status respons

Berikut ini adalah kemungkinan kode status HTTP yang dihasilkan oleh permintaan.

Kode Status	Deskripsi
200	Sukses.
304	Sumber daya belum dimodifikasi sejak versi yang ditentukan oleh header `If-None-Match`permintaan .
400	Salah satu parameter kueri tidak valid atau tidak ditemukan. Perbaiki parameter permintaan sebelum mencoba lagi.
429	Server menolak permintaan karena klien telah melampaui batas permintaan.
500	Terjadi kesalahan tak terduga. Jika kesalahan berlanjut, laporkan dengan: tanggal dan waktu kegagalan, pengidentifikasi permintaan dari header respons `X-RequestId`, dan pengidentifikasi klien dari header permintaan `X-ClientTraceId`.
503	Server tidak tersedia untuk sementara. Coba lagi permintaannya. Jika kesalahan berlanjut, laporkan dengan: tanggal dan waktu kegagalan, pengidentifikasi permintaan dari header respons `X-RequestId`, dan pengidentifikasi klien dari header permintaan `X-ClientTraceId`.

Jika terjadi kesalahan, permintaan juga akan menampilkan respons kesalahan JSON. Kode kesalahan adalah nomor 6 digit yang menggabungkan kode status HTTP 3 digit diikuti dengan nomor 3 digit untuk mengkategorikan kesalahan selengkapnya. Kode galat umum dapat ditemukan di halaman referensi Penerjemah v3.

Contoh

Contoh berikut menunjukkan cara mengambil bahasa yang didukung untuk terjemahan teks.

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

Bagikan melalui