chrome.i18n

Deskripsi

Manifes

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

Konsep dan penggunaan

Anda harus menempatkan semua string yang terlihat oleh pengguna ke dalam file bernama messages.json. Setiap kali menambahkan lokalitas baru, Anda menambahkan file pesan di direktori 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):

Mendukung beberapa bahasa

Misalkan Anda memiliki ekstensi dengan file yang ditampilkan pada gambar berikut:

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

Berikut tampilan ekstensi saat dilokalkan (perhatikan bahwa ekstensi ini masih memiliki string bahasa Inggris saja):

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, rujuk string bernama messagename seperti ini:

  __MSG_messagename__
  

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

  chrome.i18n.getMessage("messagename")
  

• Di setiap panggilan ke getMessage(), Anda dapat memberikan 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 oleh pengguna memiliki nama, item "message", dan item "description" opsional. Nama adalah kunci seperti "extName" atau "search_string" yang mengidentifikasi string. "message" menentukan nilai string dalam lokalitas ini. "description" opsional memberikan bantuan kepada penerjemah, yang mungkin tidak dapat melihat cara penggunaan string di ekstensi Anda. Contoh:

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

Untuk mengetahui informasi selengkapnya, lihat Format: Pesan Khusus Lokalitas.

Setelah diinternasionalisasi, menerjemahkan ekstensi menjadi mudah. Anda menyalin messages.json, menerjemahkannya, dan menempatkan salinan tersebut ke direktori baru di bagian /_locales. Misalnya, untuk mendukung bahasa Spanyol, cukup letakkan salinan messages.json yang diterjemahkan di bagian /_locales/es. Gambar berikut menunjukkan ekstensi sebelumnya dengan terjemahan Spanyol baru.

Pesan standar

Sistem internasionalisasi menyediakan beberapa pesan yang telah ditentukan sebelumnya untuk membantu Anda melakukan pelokalan. 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 gadgets BIDI (dua arah) API.

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

Tabel berikut menjelaskan setiap pesan standar.

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, maka baris tebal dalam 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 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 terdekat. Misalnya, jika lokalitas default ekstensi Anda adalah "de_CH", pilih "de" di Chrome Web Store.

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 terjemahan. Berikut cara sistem ekstensi menelusuri pesan:

1. Telusuri file pesan (jika ada) untuk lokalitas pilihan pengguna. Misalnya, saat lokalitas Google Chrome disetel ke Bahasa Inggris Inggris (en_GB), sistem akan mencari pesan di /_locales/en_GB/messages.json terlebih dahulu. 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 lebih lanjut.
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 "Colors", pengguna bahasa Inggris (Inggris Raya) akan melihat "Colours". Pengguna Bahasa Inggris Amerika Serikat dan Bahasa Inggris Inggris Raya 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 Anda

Untuk menguji terjemahan, Anda mungkin ingin menyetel lokalitas browser Anda. Bagian ini menjelaskan cara menyetel 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 pengujian dalam beberapa bahasa menjadi mudah. 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 lokalitas menggunakan UI di Google Chrome untuk Windows:

1. Ikon aplikasi > Opsi
2. Pilih tab Under the Hood
3. Scroll ke Konten Web
4. Klik Ubah setelan font dan bahasa
5. Pilih tab Bahasa
6. Gunakan menu drop-down untuk menyetel 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. Pilih bahasa dan lokasi Anda
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 area notifikasi, pilih Setelan.
2. Di bagian Bahasa dan input, pilih drop-down Bahasa.
3. Jika bahasa Anda tidak tercantum, klik Tambahkan bahasa, lalu tambahkan bahasa Anda.
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 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 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 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 mengetahui informasi selengkapnya tentang placeholder, lihat halaman Pesan Khusus Lokalitas. Untuk mengetahui detail tentang panggilan getMessage(), lihat referensi API.

getAcceptLanguages()

Kode berikut mengambil accept-language 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 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 mengetahui detail selengkapnya tentang cara memanggil detectLanguage(inputText), lihat referensi API.

chrome.i18n.detectLanguage(
  text: string,
): Promise<object>

chrome.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

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

chrome.i18n.getUILanguage(): string