chrome.i18n

Deskripsi

Gunakan infrastruktur chrome.i18n untuk menerapkan internasionalisasi di seluruh aplikasi atau ekstensi Anda.

Manifes

Jika ekstensi memiliki direktori /_locales, manifes harus menentukan "default_locale".

Konsep dan penggunaan

Anda harus memasukkan semua string yang terlihat oleh pengguna ke dalam file bernama messages.json. Setiap kali menambahkan lokalitas baru, Anda akan menambahkan file pesan di direktori bernama /_locales/_localeCode_, dengan localeCode adalah kode seperti en untuk bahasa Inggris.

Berikut adalah hierarki file untuk ekstensi yang diinternasionalisasi yang mendukung bahasa Inggris (en), Spanyol (es), dan Korea (ko):

Mendukung beberapa bahasa

Misalnya, Anda memiliki ekstensi dengan file yang ditampilkan dalam gambar berikut:

Untuk menerjemahkan ekstensi ini ke dalam bahasa internasional, Anda harus memberi nama setiap string yang terlihat oleh pengguna dan memasukkannya ke dalam file pesan. Manifes, file CSS, dan kode JavaScript ekstensi menggunakan nama setiap string untuk mendapatkan versi yang dilokalkan.

Berikut tampilan ekstensi saat diinternasionalisasi (perhatikan bahwa ekstensi ini masih hanya memiliki string bahasa Inggris):

Beberapa catatan tentang internasionalisasi:

• Anda dapat menggunakan salah satu lokalitas yang didukung. Jika Anda menggunakan lokalitas yang tidak didukung, Google Chrome akan mengabaikannya.

• Dalam file manifest.json dan CSS, lihat string bernama messagename seperti ini:

  __MSG_messagename__
  

• Dalam kode JavaScript ekstensi atau aplikasi, lihat string bernama messagename seperti ini:

  chrome.i18n.getMessage("messagename")
  

• Dalam setiap panggilan ke getMessage(), Anda dapat menyediakan hingga 9 string untuk disertakan dalam pesan. Lihat Contoh: getMessage untuk mengetahui detailnya.

• Beberapa pesan, seperti @@bidi_dir dan @@ui_locale, disediakan oleh sistem internasionalisasi. Lihat bagian Pesan standar untuk mengetahui daftar lengkap nama pesan standar.

• Di messages.json, setiap string yang terlihat pengguna memiliki nama, item "message", dan item "description" opsional. Namanya adalah kunci seperti "extName" atau "search_string" yang mengidentifikasi string. "message" menentukan nilai string dalam lokalitas ini. "Deskripsi" opsional memberikan bantuan kepada penerjemah, yang mungkin tidak dapat melihat cara string digunakan dalam ekstensi Anda. Contoh:

  {
    "search_string": {
      "message": "hello%20world",
      "description": "The string we search for. Put %20 between words that go together."
    },
    ...
  }
  

Untuk informasi selengkapnya, lihat Format: Pesan Khusus Lokalitas.

Setelah ekstensi diinternasionalisasi, menerjemahkannya sangat mudah. Anda menyalin messages.json, menerjemahkannya, dan memasukkan salinan ke direktori baru di bagian /_locales. Misalnya, untuk mendukung bahasa Spanyol, cukup masukkan salinan terjemahan messages.json di bagian /_locales/es. Gambar berikut menunjukkan ekstensi sebelumnya dengan terjemahan bahasa Spanyol baru.

Pesan standar

Sistem internasionalisasi menyediakan beberapa pesan standar untuk membantu Anda melakukan pelokalan. Hal ini mencakup @@ui_locale, sehingga Anda dapat mendeteksi lokalitas UI saat ini, dan beberapa pesan @@bidi_... yang memungkinkan Anda mendeteksi arah teks. Pesan terakhir memiliki nama yang mirip dengan konstanta di API BIDI (bi-directional) gadget.

Pesan khusus @@extension_id dapat digunakan dalam file CSS dan JavaScript, terlepas dari apakah ekstensi atau aplikasi dilokalkan atau tidak. Pesan ini tidak berfungsi dalam file manifes.

Tabel berikut menjelaskan setiap pesan standar.

Nama pesan	Deskripsi
@@extension_id	ID ekstensi atau aplikasi; Anda dapat menggunakan string ini untuk membuat URL untuk resource di dalam ekstensi. Bahkan ekstensi yang tidak dilokalkan dapat menggunakan pesan ini. Catatan: Anda tidak dapat menggunakan pesan ini dalam file manifes.
@@ui_locale	Lokalitas saat ini; Anda dapat menggunakan string ini untuk membuat URL khusus lokalitas.
@@bidi_dir	Arah teks untuk lokalitas saat ini, "ltr" untuk bahasa yang penulisannya dimulai dari kiri ke kanan seperti bahasa Inggris atau "rtl" untuk bahasa yang penulisannya dimulai dari kanan ke kiri seperti bahasa Arab.
@@bidi_reversed_dir	Jika @@bidi_dir adalah "ltr", maka ini adalah "rtl"; jika tidak, nilainya adalah "ltr".
@@bidi_start_edge	Jika @@bidi_dir adalah "ltr", maka ini adalah "kiri"; jika tidak, ini adalah "kanan".
@@bidi_end_edge	Jika @@bidi_dir adalah "ltr", maka ini adalah "kanan"; jika tidak, ini adalah "kiri".

Berikut adalah contoh penggunaan @@extension_id dalam file CSS untuk membuat URL:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

Jika ID ekstensi adalah abcdefghijklmnopqrstuvwxyzabcdef, baris tebal dalam cuplikan kode sebelumnya akan menjadi:

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

Berikut adalah contoh penggunaan pesan @@bidi_* dalam file CSS:

body {
  direction: __MSG_@@bidi_dir__;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi_start_edge__: 0;
  padding-__MSG_@@bidi_end_edge__: 1.5em;
  position: relative;
}

Untuk bahasa yang dibaca dari kiri ke kanan seperti bahasa Inggris, garis tebal menjadi:

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

Lokalitas

Anda dapat memilih dari banyak lokalitas, termasuk beberapa (seperti en) yang memungkinkan satu terjemahan mendukung beberapa variasi bahasa (seperti en_GB dan en_US).

Anda dapat melokalkan ekstensi ke lokalitas apa pun yang didukung oleh Chrome Web Store. Jika lokalitas Anda tidak tercantum di sini, pilih alternatif yang paling dekat. Misalnya, jika lokalitas default ekstensi Anda adalah "de_CH", pilih "de" di Chrome Web Store.

Kode lokalitas	Bahasa (wilayah)
ar	Arab
am	Amhar
bg	Bulgaria
bn	Bengali
ca	Katala
cs	Ceko
da	Denmark
de	Jerman
el	Yunani
id	Inggris
en_AU	Inggris (Australia)
en_GB	Inggris (Britania Raya)
id_ID	Inggris (AS)
es	Spanyol
es_419	Spanyol (Amerika Latin dan Karibia)
et	Estonia
fa	Persia
fi	Finlandia
fil	Filipino
fr	Prancis
gu	Gujarati
dia	Ibrani
hi	Hindi
jam	Kroasia
hu	Hungaria
id	Indonesia
it	Italia
ja	Jepang
kn	Kannada
ko	Korea
lt	Lituania
lv	Latvia
ml	Malayalam
mr	Marathi
md	Melayu
nl	Belanda
tidak	Norwegia
pl	Polandia
pt_BR	Portugis (Brasil)
pt_PT	Portugis (Portugal)
ro	Rumania
ru	Rusia
sk	Slovakia
sl	Slovenia
sr	Serbia
sv	Swedia
sw	Swahili
ta	Tamil
te	Telugu
th	Thai
tr	Turki
uk	Ukraina
vi	Vietnam
zh_CN	China (China)
zh_TW	China (Taiwan)

Menelusuri pesan

Anda tidak perlu menentukan setiap string untuk setiap lokalitas yang didukung. Selama file messages.json lokalitas default memiliki nilai untuk setiap string, ekstensi atau aplikasi Anda akan berjalan, terlepas dari seberapa jarang penerjemahannya. Berikut cara sistem ekstensi menelusuri pesan:

1. Telusuri file pesan (jika ada) untuk menemukan lokalitas pilihan pengguna. Misalnya, saat lokalitas Google Chrome disetel ke Inggris Britania Raya (en_GB), sistem akan terlebih dahulu mencari pesan di /_locales/en_GB/messages.json. Jika file tersebut ada dan pesan ada di sana, sistem tidak akan mencari lebih lanjut.
2. Jika lokalitas pilihan pengguna memiliki wilayah (yaitu, lokalitas memiliki garis bawah: _), telusuri lokalitas tanpa wilayah tersebut. Misalnya, jika file pesan en_GB tidak ada atau tidak berisi pesan, sistem akan mencari di file pesan en. Jika file tersebut ada dan pesan ada di sana, sistem tidak akan mencari lagi.
3. Telusuri file pesan untuk menemukan lokalitas default. Misalnya, jika "default_locale" ekstensi ditetapkan ke "es", dan /_locales/en_GB/messages.json maupun /_locales/en/messages.json tidak berisi pesan, ekstensi akan menggunakan pesan dari /_locales/es/messages.json.

Pada gambar berikut, pesan bernama "colores" ada di ketiga lokalitas yang didukung ekstensi, tetapi "extName" hanya ada di dua lokalitas. Di mana pun pengguna yang menjalankan Google Chrome dalam bahasa Inggris Amerika Serikat melihat label "Warna", pengguna bahasa Inggris Britania Raya akan melihat "Warna". Pengguna bahasa Inggris Amerika Serikat dan bahasa Inggris Britania Raya akan melihat nama ekstensi "Hello World". Karena bahasa defaultnya adalah Spanyol, pengguna yang menjalankan Google Chrome dalam bahasa non-Inggris akan melihat label "Colores" dan nama ekstensi "Hola mundo".

Menetapkan lokalitas browser

Untuk menguji terjemahan, sebaiknya tetapkan lokalitas browser Anda. Bagian ini menjelaskan cara menetapkan lokalitas di Windows, Mac OS, Linux, dan ChromeOS.

Windows

Anda dapat mengubah lokalitas menggunakan pintasan khusus lokalitas atau UI Google Chrome. Pendekatan pintasan lebih cepat, setelah Anda menyiapkannya, dan memungkinkan Anda menggunakan beberapa bahasa sekaligus.

Menggunakan pintasan khusus lokalitas

Untuk membuat dan menggunakan pintasan yang meluncurkan Google Chrome dengan lokalitas tertentu:

1. Buat salinan pintasan Google Chrome yang sudah ada di desktop Anda.
2. Ganti nama pintasan baru agar sesuai dengan lokalitas baru.

3. Ubah properti pintasan sehingga kolom Target menentukan tanda --lang dan --user-data-dir. Target akan terlihat seperti ini:

   path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
   

4. Luncurkan Google Chrome dengan mengklik dua kali pintasan.

Misalnya, untuk membuat pintasan yang meluncurkan Google Chrome dalam bahasa Spanyol (es), Anda dapat membuat pintasan bernama chrome-es yang memiliki target berikut:

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

Anda dapat membuat pintasan sebanyak yang Anda inginkan, sehingga mudah untuk diuji dalam beberapa bahasa. Contoh:

path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko

Catatan: Menentukan --user-data-dir bersifat opsional, tetapi praktis. Dengan memiliki satu direktori data per lokalitas, Anda dapat menjalankan browser dalam beberapa bahasa secara bersamaan. Kelemahannya adalah karena data lokalitas tidak dibagikan, Anda harus menginstal ekstensi beberapa kali—sekali per lokalitas, yang dapat menjadi tantangan jika Anda tidak dapat berbahasa tersebut. Untuk informasi selengkapnya, lihat Membuat dan Menggunakan Profil.

Menggunakan UI

Berikut cara mengubah lokalitas menggunakan UI di Google Chrome untuk Windows:

1. Ikon aplikasi > Opsi
2. Pilih tab Di Balik Layar
3. Scroll ke Konten Web
4. Klik Ubah setelan font dan bahasa
5. Pilih tab Bahasa
6. Gunakan menu drop-down untuk menetapkan bahasa Google Chrome
7. Mulai ulang Chrome

OS Mac

Untuk mengubah lokalitas di Mac, Anda menggunakan preferensi sistem.

1. Dari menu Apple, pilih System Preferences
2. Di bagian Pribadi, pilih Internasional
3. Memilih bahasa dan lokasi
4. Mulai ulang Chrome

Linux

Untuk mengubah lokalitas di Linux, tutup Google Chrome terlebih dahulu. Kemudian, dalam satu baris, tetapkan variabel lingkungan LANGUAGE dan luncurkan Google Chrome. Contoh:

LANGUAGE=es ./chrome

ChromeOS

Untuk mengubah lokalitas di ChromeOS:

1. Dari baki sistem, pilih Setelan.
2. Di bagian Bahasa dan input, pilih drop-down Bahasa.
3. Jika bahasa Anda tidak tercantum, klik Tambahkan bahasa dan tambahkan bahasa tersebut.
4. Setelah ditambahkan, klik item menu Tindakan lainnya 3 titik di samping bahasa Anda, lalu pilih Tampilkan ChromeOS dalam bahasa ini.
5. Klik tombol Mulai ulang yang muncul di samping bahasa yang ditetapkan untuk memulai ulang ChromeOS.

Contoh

Anda dapat menemukan contoh internasionalisasi di direktori examples/api/i18n. Untuk contoh lengkap, lihat examples/extensions/news. Untuk contoh lain dan bantuan dalam melihat kode sumber, lihat Contoh.

getMessage()

Kode berikut mendapatkan pesan yang dilokalkan dari browser dan menampilkannya sebagai string. Fungsi ini mengganti dua placeholder dalam pesan dengan string "string1" dan "string2".

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

Berikut cara menyediakan dan menggunakan satu string:

  // In JavaScript code
  status.innerText = chrome.i18n.getMessage("error", errorDetails);

"error": {
  "message": "Error: $details$",
  "description": "Generic error template. Expects error parameter to be passed in.",
  "placeholders": {
    "details": {
      "content": "$1",
      "example": "Failed to fetch RSS feed."
    }
  }
}

Untuk informasi selengkapnya tentang placeholder, lihat halaman Pesan Khusus Lokalitas. Untuk mengetahui detail tentang memanggil getMessage(), lihat referensi API.

getAcceptLanguages()

Kode berikut mendapatkan accept-languages dari browser dan menampilkannya sebagai string dengan memisahkan setiap accept-language dengan ','.

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

Untuk mengetahui detail tentang cara memanggil getAcceptLanguages(), lihat referensi API.

detectLanguage()

Kode berikut mendeteksi hingga 3 bahasa dari string yang diberikan dan menampilkan hasilnya sebagai string yang dipisahkan baris baru.

function detectLanguage(inputText) {
  chrome.i18n.detectLanguage(inputText, function(result) {
    var outputLang = "Detected Language: ";
    var outputPercent = "Language Percentage: ";
    for(i = 0; i < result.languages.length; i++) {
      outputLang += result.languages[i].language + " ";
      outputPercent +=result.languages[i].percentage + " ";
    }
    document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
  });
}

Untuk mengetahui detail selengkapnya tentang cara memanggil detectLanguage(inputText), lihat referensi API.

Jenis

LanguageCode

Chrome 47+

Kode bahasa ISO seperti en atau fr. Untuk mengetahui daftar lengkap bahasa yang didukung oleh metode ini, lihat kLanguageInfoTable. Untuk bahasa yang tidak diketahui, und akan ditampilkan, yang berarti [persentase] teks tidak diketahui oleh CLD

Jenis

string

Metode

detectLanguage()

Promise Chrome 47+

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

Mendeteksi bahasa teks yang diberikan menggunakan CLD.

Parameter

• teks

  string

  String input pengguna yang akan diterjemahkan.

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (result: object) => void

  • hasil

    objek

    Objek LanguageDetectionResult yang menyimpan keandalan bahasa yang terdeteksi dan array DetectedLanguage

    • isReliable

      boolean

      Keandalan bahasa yang terdeteksi CLD

    • bahasa

      object[]

      array detectedLanguage

      • language

        string

      • persentase

        angka

        Persentase bahasa yang terdeteksi

Hasil

• Promise<object>

  Chrome 99+

  Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getAcceptLanguages()

Promise

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

Mendapatkan bahasa yang diterima browser. Hal ini berbeda dengan lokalitas yang digunakan oleh browser; untuk mendapatkan lokalitas, gunakan i18n.getUILanguage.

Parameter

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (languages: string[]) => void

  • bahasa

    string[]

    Array LanguageCode

Hasil

• Promise<LanguageCode[]>

  Chrome 99+

  Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getMessage()

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

Mendapatkan string yang dilokalkan untuk pesan yang ditentukan. Jika pesan tidak ada, metode ini akan menampilkan string kosong (''). Jika format panggilan getMessage() salah — misalnya, messageName bukan string atau array substitutions memiliki lebih dari 9 elemen — metode ini akan menampilkan undefined.

Parameter

• messageName

  string

  Nama pesan, seperti yang ditentukan dalam file messages.json.

• penggantian

  apa pun opsional

  Maksimal 9 string penggantian, jika pesan memerlukannya.

• opsi

  objek opsional

  Chrome 79+
  • escapeLt

    boolean opsional

    Escape < dalam terjemahan ke <. Hal ini hanya berlaku untuk pesan itu sendiri, bukan untuk placeholder. Developer mungkin ingin menggunakannya jika terjemahan digunakan dalam konteks HTML. Template Closure yang digunakan dengan Closure Compiler akan membuatnya secara otomatis.

Hasil

• string

  Pesan yang dilokalkan untuk lokalitas saat ini.

getUILanguage()

chrome.i18n.getUILanguage()

Mendapatkan bahasa UI browser. Hal ini berbeda dengan i18n.getAcceptLanguages yang menampilkan bahasa pilihan pengguna.

Hasil

• string

  Kode bahasa UI browser seperti en-US atau fr-FR.