Форматы сообщений локализации

Каждое интернационализированное расширение имеет по крайней мере один файл messages.json , содержащий строки, специфичные для локали. На этой странице описан формат файлов messages.json . Информацию о том, как интернационализировать и локализовать, см. на странице Интернационализация .

Сводка поля

Следующий код показывает поддерживаемые поля для messages.json . Обязательны только поля « имя » и «сообщение».

сообщения.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."
      },
      ...
    }
  },
  ...
}

Пример

Вот файл messages.json , который определяет три сообщения с именами «prompt_for_name», «hello» и «bye»:

сообщения.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"
      }
    }
  }
}

Детали поля

В этом разделе описывается каждое поле, которое может отображаться в файле messages.json . Подробную информацию о том, как используется файл сообщений (например, что происходит, если локаль не определяет все сообщения), см. в разделе Интернационализация .

имя

На самом деле нет поля под названием «имя». Имя этого поля — это имя сообщения — то же имя , которое вы видите в __MSG__name___ или getMessage("_name_") .

Имя представляет собой ключ, нечувствительный к регистру, который позволяет получить локализованный текст сообщения. Имя может включать в себя следующие символы:

  • AZ
  • аз
  • 0-9
  • _ (подчеркивание)
  • @

Вот три примера имен, взятые из раздела «Примеры» :

сообщения.json:

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

Дополнительные примеры использования имен см. на странице Интернационализация .

сообщение

Переведенное сообщение в виде строки, которая может содержать заполнители . Используйте $_placeholder_name_$ (без учета регистра) для ссылки на конкретный заполнитель. Например, вы можете ссылаться на заполнитель с именем «our_site» как $our_site$ , $OUR_SITE$ или $oUR_sITe$ .

Вот три примера сообщений, взятые из раздела Пример :

сообщения.json:

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

Чтобы поместить в строку знак доллара ( $ ), используйте $$. For example, use the following code to specify the message Amount (in $):

messages.json:

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

Хотя заполнители, такие как $USER$ являются предпочтительным способом ссылки на строки замены (строки, указанные с помощью параметра замены i18n.getMessage ), вы также можете ссылаться на строки замены непосредственно внутри сообщения. Например, следующее сообщение относится к первым трем строкам замены, переданным в getMessage() :

сообщения.json:

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

Несмотря на этот пример, мы рекомендуем вам использовать заполнители вместо строк $_n_ в ваших сообщениях. Думайте о заполнителях как о хороших именах переменных. Через неделю после написания кода вы, вероятно, забудете, что означает $1 , но вы будете знать, к чему относятся ваши заполнители. Дополнительную информацию о заполнителях и строках замены см. в разделе «Заполнители» .

описание

Необязательный. Описание сообщения, предназначенное для предоставления контекста или деталей, которые помогут переводчику сделать перевод как можно лучше.

Вот три примера описаний, взятые из раздела Пример :

сообщения.json:

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

заполнители

Необязательный. Определяет одну или несколько подстрок, которые будут использоваться в сообщении. Вот две причины, по которым вы можете использовать заполнитель:

  • Чтобы определить текст для части вашего сообщения, которую не следует переводить. Примеры: HTML-код, названия торговых марок, спецификаторы форматирования.
  • Для ссылки на строку подстановки, переданную в getMessage() . Пример: $1 .

У каждого заполнителя есть имя, элемент «содержимое» и необязательный элемент «пример». Имя заполнителя не учитывает регистр и может содержать те же символы, что и имя сообщения .

Значение элемента «content» представляет собой строку, которая может ссылаться на строки подстановки, указанные с помощью параметра подстановок метода i18n.getMessage . Значение элемента «контент» обычно равно примерно «Example.com» или «$1». Если вы ссылаетесь на несуществующую строку подстановки, вы получаете пустую строку. В следующей таблице показано, как строки $_n_ соответствуют строкам, заданным параметром замены .

параметр подстановок Стоимость 1 доллара США Стоимость 2 доллара США Стоимость 3 доллара США
userName значение userName "" ""
["Cira", "Kathy"] "Cira" "Kathy" ""

Элемент «пример» (необязательный, но настоятельно рекомендуемый) помогает переводчикам, показывая, как контент выглядит для конечного пользователя. Например, заполнитель для суммы в долларах должен иметь вид "$23.45" .

В следующем фрагменте, взятом из раздела «Пример », показан элемент «заполнители», который содержит два заполнителя с именами «our_site» и «user». Заполнитель «our_site» не имеет элемента «example», поскольку его значение очевидно из поля «content».

сообщения.json:

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