Ссылка на справочник сообщений, зависящих от региона

Следующий код демонстрирует пример messages.json file, взятый из нашего расширения-примера notify-link-clicks-i18n. Поля «name» и «message» являются обязательными.

{
  "extensionName": {
    "message": "Notify link clicks i18n",
    "description": "Name of the extension."
  },

  "extensionDescription": {
    "message": "Shows a notification when the user clicks on links.",
    "description": "Description of the extension."
  },

  "notificationTitle": {
    "message": "Click notification",
    "description": "Title of the click notification."
  },

  "notificationContent": {
    "message": "You clicked $URL$.",
    "description": "Tells the user which link they clicked.",
    "placeholders": {
      "url" : {
        "content" : "$1",
        "example" : "https://developer.mozilla.org"
      }
    }
  }
}

Файлы messages.json должны быть размещены внутри каталогов, названных в соответствии с языком, который поддерживает каждый файл — en, de, ja, и т. д. В свою очередь, эти каталоги должны находиться внутри каталога с именем _locales, расположенного в корне расширения.

В этом разделе описаны каждый элемент, который может присутствовать в файле messages.json.

Каждый элемент верхнего уровня называется по имени строки сообщения, которое вы локализуете, например, "extensionName" или "notificationContent" в примере выше. Каждое имя нечувствительно к регистру и служит ключом для извлечения текста локализованного сообщения.

Имя может содержать следующие символы:

• A-Z
• a-z
• 0-9
• _ (нижняя черта)
• @

Для каждой строки обязательно должно быть задано это свойство. Элемент "message" содержит локализованную строку, которая может содержать заполнители. Вы можете использовать:

• $placeholder_name$ (регистр игнорируется) для вставки конкретного заполнителя (например, $URL$ в примере выше) в вашу строку.
• $1, $2, $3, и т. д. для прямой вставки значений, полученных из вызова i18n.getMessage(), в вашу строку.

Другие моменты:

• Любое количество последовательных знаков доллара, появляющихся в строках, заменяется на то же количество знаков доллара минус один. Например, $$ > $, $$$ > $$, и т. д.
• При чтении файла локализации токены, соответствующие /\$([a-z0-9_@]+)\$/i, заменяются соответствующим значением из объекта «placeholders» строки. Эти замены происходят до обработки любых токенов /\$\d/ в сообщении.
• При использовании строки локализации токены, соответствующие /\$\d+/, заменяются значениями, переданными в i18n.getMessage().
• getMessage() не будет обрабатывать вызовы с более чем 9 заменителями/заполнителями.

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

Элемент "placeholders" определяет один или несколько подстрок-заполнителей, которые будут использоваться внутри сообщения — они могут использоваться для кодирования элементов, которые вы не хотите переводить, или для ссылки на переменные.

Каждое определение подстроки-заполнителя имеет ряд собственных значений:

"url" : {
  "content" : "$1",
  "example" : "https://developer.mozilla.org"
}

Имя заполнителя

Имя заполнителя используется для представления заполнителя в строке подстановки (например, "url" преобразуется в $url$). Оно нечувствительно к регистру и может содержать те же символы, что и имя сообщения.

содержимое

Элемент «content» определяет содержимое заполнителя. Это может быть жёстко закодированная строка, например, «Мой заполнитель», но она также может содержать значения, полученные из вызова i18n.getMessage(). Это свойство обязательно. Дополнительную информацию см. в разделе Получение строк сообщений из JavaScript.

пример

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