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 pada direktori yang bernama /_locales/_localeCode_, dengan localeCode adalah kode seperti en untuk bahasa Inggris.

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

Di direktori ekstensi: manifest.json, *.html, *.js, /_ mengemudis. Dalam direktori /_=s: en, es, dan ko, masing-masing dengan sebuah file messages.json.

Mendukung beberapa bahasa

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

File manifest.json dan file dengan JavaScript. File .json memiliki

Untuk menginternasionalkan ekstensi ini, beri nama setiap string yang terlihat oleh pengguna dan masukkan ke dalam file pesan. Manifes ekstensi, file CSS, dan kode JavaScript menggunakan setiap nama string untuk mendapatkan versi yang dilokalkan.

Berikut tampilan ekstensi saat diinternasionalkan (perlu diperhatikan bahwa ekstensi hanya memiliki string bahasa Inggris):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _ berjumlah

Beberapa catatan tentang penginternasionalan:

  • 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__

  • Di kode JavaScript aplikasi atau ekstensi Anda, 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 yang telah ditetapkan.

  • Di messages.json, setiap string yang terlihat oleh pengguna memiliki nama, item "pesan", dan item "deskripsi" opsional. Nama berupa kunci seperti "extName" atau "search_string" yang mengidentifikasi string. "Pesan" 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 Lokal.

Setelah ekstensi diinternasionalkan, penerjemahannya menjadi mudah. Anda menyalin messages.json, menerjemahkannya, dan menempatkan salinan ke direktori baru di bawah /_locates. Misalnya, untuk mendukung bahasa Spanyol, cukup masukkan salinan terjemahan messages.json di bawah /_locates/es. Gambar berikut menunjukkan ekstensi sebelumnya dengan terjemahan bahasa Spanyol baru.

File ini terlihat sama dengan gambar sebelumnya, tetapi dengan file baru di /_ buckets/es/messages.json yang berisi terjemahan bahasa Spanyol dari pesan tersebut.

Pesan standar

Sistem internasionalisasi menyediakan beberapa pesan standar untuk membantu Anda melokalkan. Ini termasuk @@ui_locale, sehingga Anda dapat mendeteksi lokalitas UI saat ini, dan beberapa pesan @@bidi_... yang memungkinkan Anda mendeteksi arah teks. Pesan yang terakhir memiliki nama yang mirip dengan konstanta di API BIDI (dua arah) gadget.

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

Tabel berikut menjelaskan setiap pesan standar.

Nama pesanDeskripsi
@@extension_idEkstensi atau ID aplikasi; Anda dapat menggunakan string ini untuk membuat URL bagi resource di dalam ekstensi. Bahkan ekstensi yang tidak dilokalkan dapat menggunakan pesan ini.
Catatan: Anda tidak dapat menggunakan pesan ini dalam file manifes.
@@ui_localeLokal saat ini; Anda dapat menggunakan string ini untuk membuat URL khusus lokal.
@@bidi_dirArah teks untuk lokalitas saat ini, "ltr" untuk bahasa yang ditulis dari kiri ke kanan seperti bahasa Inggris atau "rtl" untuk bahasa yang ditulis dari kanan ke kiri seperti bahasa Jepang.
@@bidi_reversed_dirJika @@bidi_dir adalah "ltr", maka ini adalah "rtl"; jika tidak, "ltr".
@@bidi_start_edgeJika @@bidi_dir adalah "ltr", maka nilainya adalah "left"; jika tidak, nilainya adalah "right".
@@bidi_end_edgeJika @@bidi_dir adalah "ltr", nilainya adalah "right"; jika tidak, nilainya adalah "left".

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 di cuplikan kode sebelumnya 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 penulisannya dari kiri ke kanan seperti bahasa Inggris, baris yang dicetak tebal menjadi:

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

Lokal

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

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

Kode lokal Bahasa (wilayah)
ar Arab
am Amhar
bg Bulgaria
bn Bengali
ca Katala
cs Ceko
da Denmark
de Jerman
el Yunani
en Inggris
en_AU Inggris (Australia)
en_GB Inggris (Britania Raya)
en_US Inggris (Amerika Serikat)
es Spanyol
es_419 Spanyol (Amerika Latin dan Karibia)
et Estonia
fa Persia
fi Finlandia
fil Filipino
fr Prancis
gu Gujarati
he 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
ms Malaysia
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 Turkiye
uk Ukraina
vi Vietnam
zh_CN China (China)
zh_TW China (Taiwan)

Menelusuri pesan

Anda tidak harus 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 terjemahannya. Berikut cara sistem ekstensi menelusuri pesan:

  1. Telusuri file pesan (jika ada) untuk menemukan lokalitas pilihan pengguna. Misalnya, jika lokalitas Google Chrome disetel ke bahasa Inggris Britania Raya (en_GB), sistem akan mencari pesan tersebut dalam /_locates/en_GB/messages.json terlebih dahulu. Jika file tersebut ada dan pesan ada di sana, sistem tidak akan mencari lagi.
  2. Jika lokalitas pilihan pengguna memiliki wilayah (yaitu, lokalitas yang 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 pesannya ada di sana, sistem tidak akan mencari lagi.
  3. Telusuri file pesan untuk lokalitas default. Misalnya, jika "default_locale" ekstensi ditetapkan ke "es", dan /_locates/en_GB/messages.json atau /_locates/en/messages.json tidak berisi pesan, ekstensi akan menggunakan pesan dari /_locates/es/messages.json.

Dalam 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 AS akan melihat label "Warna", pengguna bahasa Inggris Britania akan melihat "Warna". Pengguna bahasa Inggris AS dan Inggris Britania Raya melihat nama ekstensi "Hello World". Karena bahasa defaultnya adalah bahasa Spanyol, pengguna yang menjalankan Google Chrome dalam bahasa selain Inggris akan melihat label "Warna" dan nama ekstensi "Hola mundo".

Empat file: manifest.json dan tiga file messages.json (untuk es, en, dan en_GB). File es dan en menampilkan entri untuk pesan yang bernama

Setel lokalitas browser Anda

Untuk menguji terjemahan, Anda dapat menyetel lokalitas browser. Bagian ini menjelaskan cara menyetel lokalitas di Windows, Mac OS X, Linux, dan ChromeOS.

Windows

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

Menggunakan pintasan khusus lokal

Untuk membuat dan menggunakan pintasan yang membuka Google Chrome dengan lokal tertentu:

  1. Buat salinan pintasan Google Chrome yang sudah ada di desktop Anda.
  2. Ganti nama pintasan baru agar cocok 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 memudahkan pengujian dalam berbagai 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
Menggunakan UI

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

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

Mac OS X

Untuk mengubah lokalitas di Mac, gunakan preferensi sistem.

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

Linux

Untuk mengubah lokalitas di Linux, keluar dari Google Chrome terlebih dahulu. Kemudian, semuanya dalam satu baris, setel 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 ada dalam daftar, klik Tambahkan bahasa, lalu tambahkan.
  4. Setelah ditambahkan, klik item menu 3 titik Tindakan lainnya di samping bahasa Anda, lalu pilih Tampilkan ChromeOS dalam bahasa ini.
  5. Klik tombol Mulai ulang yang muncul di samping bahasa yang disetel untuk memulai ulang ChromeOS.

Contoh

Anda dapat menemukan contoh sederhana 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. Ini menggantikan 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 adalah cara menyediakan dan menggunakan string tunggal:

  // 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 mengetahui informasi selengkapnya tentang placeholder, lihat halaman Pesan Khusus Lokal. Untuk mengetahui detail tentang memanggil getMessage(), lihat referensi API.

getAcceptLanguages()

Kode berikut mendapatkan bahasa penerimaan dari browser dan menampilkannya sebagai string dengan memisahkan setiap bahasa penerimaan dengan ','.

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

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

detectLanguage()

Kode berikut mendeteksi hingga 3 bahasa dari string yang diberikan dan menampilkan hasilnya sebagai string yang dipisahkan oleh 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 detail selengkapnya tentang 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 disediakan menggunakan CLD.

Parameter

  • teks

    string

    String input pengguna yang akan diterjemahkan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (result: object)=>void

    • hasil

      objek

      Objek LanguageDetectedionResult yang berisi mendeteksi keandalan bahasa dan array DetectedLanguage

      • isReliable

        boolean

        CLD mendeteksi keandalan bahasa

      • bahasa

        objek[]

        array detectedLanguage

        • language

          string

        • persentase

          angka

          Persentase bahasa yang terdeteksi

Hasil

  • Promise<object>

    Chrome 99 dan yang lebih baru

    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 penerimaan browser. Bahasa ini berbeda dari lokal 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 dan yang lebih baru

    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.

  • substitusi

    opsional

    Hingga 9 string substitusi, jika pesan diperlukan.

  • opsi

    objek opsional

    Chrome 79 dan yang lebih baru
    • escapeLt

      boolean opsional

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

Hasil

  • string

    Pesan dilokalkan untuk lokalitas saat ini.

getUILanguage()

chrome.i18n.getUILanguage()

Mendapatkan bahasa UI browser dari browser. Ini berbeda dengan i18n.getAcceptLanguages yang menampilkan bahasa pengguna pilihan.

Hasil

  • string

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