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

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

Краткое описание области

Приведённый ниже код демонстрирует поддерживаемые поля для messages.json . Обязательными являются только поля " name " и "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."
      },
      ...
    }
  },
  ...
}

Пример

Вот файл messages.json , в котором определены три сообщения с именами "prompt_for_name", "hello" и "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"
      }
    }
  }
}

Детали поля

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

имя

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

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

  • АЗ
  • аз
  • 0-9
  • _ (нижнее подчеркивание)
  • @
Примечание: Не указывайте имена, начинающиеся с "@@". Эти имена зарезервированы для предопределенных сообщений .

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

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

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

сообщение

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

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

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

"message": "Amount (in $$)" Хотя использование заполнителей, таких как $USER$ является предпочтительным способом обращения к строкам подстановки (строкам, указанным с помощью параметра substitutions функции i18n.getMessage ), вы также можете обращаться к строкам подстановки непосредственно в сообщении. Например, следующее сообщение ссылается на первые три строки подстановки, переданные в getMessage() :
"message": "Params: $1, $2, $3"

 Несмотря на этот пример, мы рекомендуем использовать заполнители вместо строк $_n_ в ваших сообщениях. Рассматривайте заполнители как хорошие имена переменных. Через неделю после написания кода вы, вероятно, забудете, на что ссылается $1 , но будете знать, на что ссылаются ваши заполнители. Более подробную информацию о заполнителях и строках подстановки см. в разделе «Заполнители» .
 описание
 Необязательно. Описание сообщения, призванное предоставить контекст или детали, которые помогут переводчику сделать максимально качественный перевод.
 Вот три примера описаний, взятые из раздела «Примеры» :
"description": "Ask for the user's name"
...
"description": "Greet the user"
...
"description": "Say goodbye to the user"

 заполнители
 Необязательный параметр. Определяет одну или несколько подстрок, которые будут использоваться в сообщении. Вот две причины, по которым вы можете захотеть использовать заполнитель:
  •  Для определения текста той части вашего сообщения, которая не подлежит переводу. Примеры: HTML-код, зарегистрированные товарные знаки, спецификаторы форматирования.
  •  Для ссылки на строку подстановки, переданную в функцию getMessage() . Пример: $1 .
 Каждый заполнитель имеет имя, элемент «содержимое» и необязательный элемент «пример». Имя заполнителя нечувствительно к регистру и может содержать те же символы, что и имя сообщения .
 Значение элемента "content" представляет собой строку, которая может ссылаться на строки подстановки, задаваемые с помощью параметра substitutions метода i18n.getMessage . Значение элемента "content" обычно выглядит примерно так: "Example.com" или "$1". Если вы ссылаетесь на несуществующую строку подстановки, вы получаете пустую строку. В следующей таблице показано, как строки $_n_ соответствуют строкам, указанным параметром substitutions .
 параметр подстановок Стоимость 1 доллара Стоимость 2 долларов Стоимость 3 долларов
 userName значение userName "" ""
 ["Cira", "Kathy"] "Cira" "Kathy" ""
 Пункт «Пример» (необязательный, но настоятельно рекомендуемый) помогает переводчикам, показывая, как контент выглядит для конечного пользователя. Например, для заполнения поля с суммой в долларах следует указать пример, например "$23.45" .
 Следующий фрагмент кода, взятый из раздела «Примеры» , показывает элемент «Заполнители», содержащий два заполнителя с именами «our_site» и «user». Заполнитель «our_site» не имеет элемента «Пример», поскольку его значение очевидно из поля «Содержание».
"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}