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)
- @
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à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ư 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 USD | Giá trị 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 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"
}
}