Format pesan pelokalan

Setiap ekstensi yang diinternasionalkan memiliki setidaknya satu file bernama messages.json yang menyediakan string khusus lokal. Halaman ini menjelaskan format file messages.json. Untuk informasi tentang cara menginternasionalkan dan melokalkan, lihat halaman Internasionalisasi.

Ringkasan kolom

Kode berikut menunjukkan kolom yang didukung untuk messages.json. Hanya kolom "name" dan "message" yang wajib diisi.

messages.json:

{
  "name": {
    "message": "Message text, with optional placeholders.",
    "description": "Translator-aimed description of the message.",
    "placeholders": {
      "placeholder_name": {
        "content": "A string to be placed within the message.",
        "example": "Translator-aimed example of the placeholder string."
      },
      ...
    }
  },
  ...
}

Contoh

Berikut adalah file messages.json yang menentukan tiga pesan bernama "prompt_for_name", "hello", dan "bye":

messages.json:

{
  "prompt_for_name": {
    "message": "What's your name?",
    "description": "Ask for the user's name"
  },
  "hello": {
    "message": "Hello, $USER$",
    "description": "Greet the user",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  },
  "bye": {
    "message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!",
    "description": "Say goodbye to the user",
    "placeholders": {
      "our_site": {
        "content": "Example.com",
      },
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  }
}

Detail kolom

Bagian ini menjelaskan setiap kolom yang dapat muncul di file messages.json. Untuk mengetahui detail tentang cara file pesan digunakan—misalnya, apa yang terjadi jika lokalitas tidak menentukan semua pesan—lihat Internasionalisasi.

name

Sebenarnya, tidak ada kolom bernama "name". Nama kolom ini adalah nama pesan—nama sama dengan yang Anda lihat di __MSG__name___ atau getMessage("_name_").

Nama adalah kunci yang tidak peka huruf besar/kecil yang memungkinkan Anda mengambil teks pesan yang dilokalkan. Nama dapat menyertakan karakter berikut:

  • A-Z
  • a-z
  • 0-9
  • _ (garis bawah)
  • @

Berikut tiga contoh nama, yang diambil dari bagian Contoh:

messages.json:

"prompt_for_name": {
  ...
},
"hello": {
  ...
},
"bye": {
  ...
}

Untuk contoh penggunaan nama lainnya, lihat halaman Internasionalisasi.

pesan

Pesan yang diterjemahkan, dalam bentuk string yang dapat berisi placeholders. Gunakan $_placeholder_name_$ (tidak peka huruf besar/kecil) untuk merujuk ke placeholder tertentu. Misalnya, Anda dapat merujuk ke placeholder bernama "our_site" sebagai $our_site$, $OUR_SITE$, atau $oUR_sITe$.

Berikut adalah tiga contoh pesan, yang diambil dari bagian Contoh:

messages.json:

"message": "What's your name?"
...
"message": "Hello, $USER$"
...
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"

Untuk menempatkan tanda dolar ($) ke dalam string, gunakan $$. For example, use the following code to specify the message Amount (in $):

messages.json:

"message": "Amount (in $$)"


Meskipun placeholder seperti $USER$ adalah cara yang direkomendasikan untuk merujuk ke string substitusi (string yang ditentukan menggunakan parameter substitutions dari i18n.getMessage), tetapi Anda juga dapat merujuk ke string substitusi secara langsung dalam pesan. Misalnya, pesan berikut mengacu pada tiga string substitusi pertama yang diteruskan ke getMessage():



messages.json:


"message": "Params: $1, $2, $3"



Meskipun demikian, sebaiknya tetap gunakan placeholder, bukan string $_n_ dalam pesan Anda. Pikirkan {i>placeholder<i} sebagai nama variabel yang baik. Seminggu setelah menulis kode, Anda mungkin akan lupa apa yang dimaksud dengan $1, tetapi Anda akan mengetahui apa yang dimaksud dengan placeholder.
Untuk mengetahui informasi selengkapnya tentang placeholder dan string substitusi, lihat bagian placeholders.



deskripsi



Opsional. Deskripsi pesan, yang dimaksudkan untuk memberikan konteks atau detail guna membantu penerjemah
membuat terjemahan terbaik.



Berikut tiga contoh deskripsi, yang diambil dari bagian Contoh:



messages.json:


"description": "Ask for the user's name"
...
"description": "Greet the user"
...
"description": "Say goodbye to the user"



placeholders



Opsional. Menentukan satu atau beberapa substring yang akan digunakan dalam pesan. Berikut adalah dua alasan Anda
mungkin ingin menggunakan placeholder:



    

  • Untuk menentukan teks pada bagian pesan Anda yang tidak boleh diterjemahkan. Contoh: kode HTML,
nama merek dagang, penentu pemformatan.
    • 

  • Untuk merujuk ke string substitusi yang diteruskan ke getMessage(). Contoh: $1.
    • 




Setiap placeholder memiliki nama, item "konten", dan item "contoh" opsional. Nama placeholder tidak peka huruf besar/kecil dan dapat berisi karakter yang sama dengan nama pesan.



Nilai item "content" adalah string yang dapat merujuk ke string substitusi, yang ditentukan
menggunakan parameter substitutions metode i18n.getMessage. Nilai item "content" biasanya
seperti "Example.com" atau "$1". Jika Anda merujuk ke string substitusi yang tidak ada, Anda akan mendapatkan string kosong. Tabel berikut menunjukkan bagaimana string $_n_ sesuai dengan string
yang ditentukan oleh parameter substitutions.



parameter substitutionsNilai $1Nilai $2Nilai $3
userNamenilai userName""""
["Cira", "Kathy"]"Cira""Kathy"""



Item "contoh" (opsional, tetapi sangat direkomendasikan) membantu penerjemah dengan menunjukkan tampilan konten
kepada pengguna akhir. Misalnya, placeholder untuk jumlah dolar harus memiliki contoh seperti
"$23.45".



Cuplikan berikut, yang diambil dari bagian Contoh, menunjukkan item "placeholder" yang berisi dua placeholder bernama "our_site" dan "user". Placeholder "our_site" tidak memiliki item "example" karena nilainya jelas dari kolom "content".



messages.json:


"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}