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

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

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

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

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

"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à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ô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"
  }
}