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

Mỗi tiện ích quốc tế hoá có ít nhất một tệp có tên messages.json. Tệp này cung cấp các chuỗi theo từng ngôn ngữ cụ thể. Trang này mô tả định dạng của các 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ỉ bắt buộc phải sử dụng các trường "name" và "message".

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

Ví dụ:

Dưới đây là tệp messages.json xác định 3 thông báo có tên "prompt_for_name", "hello" và "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"
      }
    }
  }
}

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, chẳng hạn như đ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 phần 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 – giống với tên mà bạn thấy trong __MSG__name___ hoặc getMessage("_name_").

Tên là 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)
• @

Lưu ý: Đừng xác định tên bắt đầu bằng "@@". Những tên đó được dành riêng cho thông báo đã xác định trước.

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

messages.json:

"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ạng một chuỗi có thể chứa các placeholders. 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 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à ba ví dụ về thông báo, được lấy từ phần Ví dụ:

messages.json:

"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 $):

messages.json:

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

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

messages.json:
"message": "Params: $1, $2, $3"

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

description

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

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

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

placeholders

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


Để xác định văn bản cho một phần thông báo không được dịch. Ví dụ: Mã HTML, tên đã đăng ký nhãn hiệu, thông số đị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 như tên thông báo.

Giá trị của mục "content" 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 thông số thay thế của phương thức i18n.getMessage. Giá trị của mục "nội dung" thường đại diện 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ố thay thế chỉ định.

thông số thay thế
Giá trị 1 USD
Giá trị 2 USD
Giá trị 3 USD
userName
giá trị của userName
""
""
["Cira", "Kathy"]
"Cira"
"Kathy"
""

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

Đoạn mã sau, lấy từ phần Ví dụ, cho thấy một mục "phần giữ chỗ" 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 "example" vì giá trị của phần này hiển thị rõ ràng trong trường "content".

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