Định dạng thông báo bản địa hoá

Mỗi ứng dụng hoặc tiện ích quốc tế hoá có ít nhất một tệp có tên messages.json cung cấp chuỗi dành riêng cho từng ngôn ngữ. Trang này mô tả định dạng của tệp messages.json. Để biết thông tin về cách quốc tế hoá và bản địa hoá, hãy xem trang Quốc tế hoá.

Tóm tắt trường

Mã sau đây cho thấy các trường được hỗ trợ cho messages.json. Chỉ "name" và "tin nhắn" là trường bắt buộc.

{
  "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."
      },
      ...
    }
  },
  ...
}

Ví dụ:

Dưới đây là tệp messages.json xác định ba thông báo có tên "prompt_for_name", "hello" và "bye":

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

Thông tin chi tiết về trường

Phần này mô tả từng trường có thể xuất hiện trong tệp messages.json. Để biết chi tiết về cách thông báo được sử dụng—ví dụ: điều gì xảy ra khi một ngôn ngữ không xác định tất cả các thông báo—hãy xem Quốc tế hoá.

tên

Trên thực tế, không có trường nào có tên là "tên". Tên của trường này là tên của thông báo—giống với name mà bạn thấy trong __MSG__name___ hoặc getMessage("_name_").

Tên là một khoá không phân biệt chữ hoa chữ thường cho phép bạn truy xuất văn bản thông báo đã bản địa hoá. Tên này có thể chứa các ký tự sau:

  • A-Z
  • a-z
  • 0-9
  • _ (dấu gạch dưới)
  • @
Lưu ý: Không xác định tên bắt đầu bằng "@@". Những tên đó được dành riêng cho tin nhắn được xác định trước.

Dưới đây là 3 ví dụ về tên, được lấy từ phần Ví dụ:

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

Để xem thêm ví dụ về cách sử dụng tên, hãy xem trang Quốc tế hoá.

tin nhắn

Thông báo đã được dịch, dưới dạng một chuỗi có thể chứa phần giữ chỗ. Sử dụng $_placeholder_name_$ (không phân biệt chữ hoa chữ thường) để đề cập đến một phần giữ chỗ cụ thể. Ví dụ: bạn có thể tham chiếu đến phần giữ chỗ có tên là "our_site" dưới dạng $our_site$, $OUR_SITE$ hoặc $oUR_sITe$.

Dưới đây là ba ví dụ về thông báo được lấy từ phần Ví dụ:

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

Để đặt ký hiệu đô la ($) vào chuỗi, hãy sử dụng $$. For example, use the following code to specify the message Amount (in $):

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


Mặc dù phần giữ chỗ, chẳng hạn như $USER$ là cách tham chiếu ưu tiên đến chuỗi thay thế
(các chuỗi được chỉ định bằng tham số thay thế của i18n.getMessage), bạn cũng có thể tham chiếu
vào chuỗi thay thế ngay trong thông báo. Ví dụ: thông báo sau đây đề cập đến
ba chuỗi thay thế đầu tiên được truyền vào getMessage():


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



Bất kể ví dụ đó, bạn nên tiếp tục sử dụng phần giữ chỗ thay vì chuỗi $_n_
trong thư của bạn. Hãy coi phần giữ chỗ là tên biến phù hợp. Một tuần sau khi bạn viết
mã, bạn có thể sẽ quên $1 đề cập đến nội dung gì, nhưng bạn sẽ biết phần giữ chỗ của bạn đề cập đến điều gì.
Để biết thêm thông tin về phần giữ chỗ và chuỗi thay thế, hãy xem phần phần giữ chỗ.



description



Không bắt buộc. Nội dung mô tả về thông báo, nhằm cung cấp ngữ cảnh hoặc thông tin chi tiết để giúp người dịch tạo ra bản dịch tốt nhất có thể.



Dưới đây là 3 ví dụ về nội dung mô tả, được lấy từ phần Ví dụ:


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



phần giữ chỗ



Không bắt buộc. Xác định một hoặc nhiều chuỗi con để sử dụng trong thông báo. Sau đây là hai lý do bạn nên sử dụng phần giữ chỗ:



    

  • Để xác định văn bản cho một phần của thông báo không nên được dịch. Ví dụ: mã HTML, tên đã đăng ký nhãn hiệu, chỉ định định dạng.
    • 

  • Để tham chiếu đến một chuỗi thay thế được truyền vào getMessage(). Ví dụ: $1.
    • 




Mỗi phần giữ chỗ có một tên, một mục "nội dung" và một mục "ví dụ" (không bắt buộc). Tên của phần giữ chỗ không phân biệt chữ hoa chữ thường và có thể chứa các ký tự giống với tên thông báo.



Phần "content" (Nội dung) giá trị của mục là một chuỗi có thể tham chiếu đến các chuỗi thay thế, được chỉ định
bằng cách sử dụng tham số thay thế của phương thức i18n.getMessage. Giá trị của một "nội dung" mục là
thường là ví dụ như "Example.com" hoặc "$1". Nếu tham chiếu đến một chuỗi thay thế không tồn tại, bạn sẽ nhận được một chuỗi trống. Bảng sau đây cho thấy cách các chuỗi $_n_ tương ứng với các chuỗi do tham số substitutions chỉ định.



tham số thay thếGiá trị là 1 USDGiá trị 2 USDGiá trị là 3 USD
userNamegiá trị của userName""""
["Cira", "Kathy"]"Cira""Kathy"""



Mục "ví dụ" (không bắt buộc nhưng rất nên dùng) giúp người dịch bằng cách cho thấy nội dung sẽ xuất hiện như thế nào với người dùng cuối. Ví dụ: phần giữ chỗ cho số tiền nên có ví dụ như
"$23.45".



Đoạn mã sau (được lấy từ phần Ví dụ) cho thấy một "phần giữ chỗ" mặt hàng
chứa hai phần giữ chỗ có tên là "our_site" và "người dùng". Phần giữ chỗ "our_site" không có mục "ví dụ" vì giá trị của phần giữ chỗ này đã rõ ràng trong trường "content".


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