Mỗi tiện ích hoặc ứng dụng đã quốc tế hoá có ít nhất một tệp tên là messages.json cung cấp các chuỗi dành riêng cho 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ỉ yêu cầu các trường "name" và "message".
{
"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 thông tin chi tiết về cách sử dụng tệp thông báo (ví dụ: điều gì sẽ xảy ra khi một ngôn ngữ không xác định tất cả thông báo), hãy xem phần Quá trình quốc tế hoá.
tên
Thực ra, không có trường nào có tên là "name". Tên của trường này là tên của thông báo – chính là tên 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ể bao gồm các ký tự sau:
- A-Z
- a – z
- 0-9
- _ (dấu gạch dưới)
- @
Dưới đây là 3 ví dụ về tên, được lấy từ phần Ví dụ:
"prompt_for_name": {
...
},
"hello": {
...
},
"bye": {
...
}
Để biết 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) để tham chiếu đế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 "our_site" dưới dạng $our_site$, $OUR_SITE$ hoặc $oUR_sITe$.
Dưới đây là 3 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 dấ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ỗ như
$USER$là cách ưu tiên để tham chiếu đến chuỗi thay thế (chuỗi được chỉ định bằng tham số substitutions của i18n.getMessage), nhưng bạn cũng có thể tham chiếu trực tiếp đến chuỗi thay thế 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àogetMessage():"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ông báo. Hãy coi phần giữ chỗ là tên biến phù hợp. Một tuần sau khi viết mã, có thể bạn sẽ quên$1đề cập đến nội dung gì, nhưng bạn sẽ biết phần giữ chỗ đề cập đến nội dung 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ể.
Sau đây là 3 ví dụ về nội dung mô tả 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 "content" (nội dung) và một mục "example" (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.
Giá trị của mục "content" (nội dung) là một chuỗi có thể tham chiếu đến các chuỗi thay thế được chỉ định bằng tham số substitutions (phần thay thế) của phương thức i18n.getMessage. Giá trị của mục "content" (nội dung) thường là "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 chuỗi $_n_ tương ứng với chuỗi do tham số substitutions chỉ định.
| Tham số substitutions (phần thay thế) | Giá trị là 1 USD | Giá trị là 2 USD | Giá trị là 3 USD |
|---|---|---|---|
userName | giá 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 bằng đô la phải có ví dụ như "$23.45".
Đoạn mã sau (được lấy từ phần Ví dụ) cho thấy một mục "phần giữ chỗ" chứa 2 phần giữ chỗ có tên là "our_site" và "user". Phần giữ chỗ "our_site" không có mục "example" vì giá trị của nó rõ ràng trong trường "content".
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}