Интернационализация

API WebExtensions предоставляет полезный модуль для интернационализации расширений — i18n. В этой статье мы рассмотрим его особенности и пример его работы. Система для расширений, построенных с помощью API WebExtension, i18n похожа на библиотеки JavaScript для i18n, такие как i18n.js.

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

• корневая-директория-расширения/
  • _locales
    • en
      • messages.json
        • Сообщения на английском (строки)
    • de
      • messages.json
        • Сообщения на немецком (строки)
    • и т. д.
  • manifest.json
    • Метаданные, зависящие от локализации
  • myJavascript.js
    • Файл JavaScript, получающий локализацию браузера, сообщения, зависящие от локализации, и т. д.
  • myStyles.css
    • CSS, зависящий от локализации

Давайте отдельно рассмотрим каждый элемент — последующие секции представляют собой шаги, которым стоит следовать во время интернационализации вашего расширения.

Каждая система i18n требует предоставить строки во всех локализациях, которые вы хотите поддерживать. В расширениях они хранятся в директории  _locales, размещённой внутри корневой директории. Строки каждой локализации (также называемые сообщениями) хранятся в файле messages.json, находящемся в поддиректории _locales, название которой - тег языка локализации.

Стоит заметить, что если тег включает в себя и базовый язык, и его региональный вариант, то по конвенции эти язык и вариант разделяются дефисом: например, "en-US". Однако в поддиректориях _locales, вместо дефиса используется нижнее подчёркивание: "en_US".

Таким образом, в нашем примере существую директории "en" (английский), "de" (немецкий), "nl" (голландский), and "ja" (японский). Внутри каждой из них находится файл messages.json .

Давайте рассмотрим структуру одного из этих файлов (_locales/en/messages.json):

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

Это стандартный файл JSON — каждый из его элементов является объектом с именем, содержащим сообщение (message) и описание (description). Оба предмета - строки; $URL$ — это заполнитель, который заменяется подстрокой, когда элемент notificationContent вызывается расширением. Вы научитесь это делать в секции Получение сообщений из JavaScript.

Для интернационализации файла manifest.json нужно предпринять несколько шагов.

Ваш файл manifest.json содержит строки, отображаемые пользователю, такие как имя и описание расширения. Если вы интернационализируете эти строки и поместите их переводы в messages.json, то эти переводы будут отображаться пользователю в зависимости от локализации его браузера.

Чтобы интернационализировать строки, их нужно указывать следующим образом:

"name": "__MSG_extensionName__",
"description": "__MSG_extensionDescription__",

Здесь мы получаем сообщения, зависящие от локализации браузера, а не просто статические строки.

Чтобы получить строку сообщения, её нужно указать следующим образом:

1. Два подчёркивания
2. Строка "MSG"
3. Одно подчёркивание
4. Имя сообщения так как оно указано в messages.json
5. Два подчёркивания

__MSG_ + messageName + __

Ещё одно поле. которое нужно указать в manifest.json — это default_locale:

"default_locale": "en"

Этот параметр устанавливает локализацию по умолчанию, используемую, если расширение не поддерживает локализацию браузера пользователя. Любые сообщения, недоступные в текущей локализации, будут браться из той локализации, которая установлена по умолчанию. There are some more details to be aware of in terms of how the browser selects strings — see Выбор локализованной строки.

Локализованные строки также можно получить из CSS-файлов расширения. Например, вы можете создать поля CSS, зависящие от локализации, так:

header {
  background-image: url(../images/__MSG_extensionName__/header.png);
}

Эта функциональность может быть полезна, однако, возможно, для этих целей стоит использовать Заранее определённые сообщения.

Допустим, вы добавили сообщения в ваш manifest.json. Чтобы ваше расширение начало использовать правильные языки, соответствующие сообщения следует вызывать при помощи JavaScript. API i18n достаточно прост и содержит всего 4 основных метода:

• Скорее всего, наиболее часто вы будете использовать i18n.getMessage() (en-US) — этот метод используется для получения конкретного сообщения. Примеры его использования можно увидеть ниже.
• Методы i18n.getAcceptLanguages() (en-US) и i18n.getUILanguage() (en-US) используются, если UI надо менять в зависимости от локализации — например, если вы хотите, чтобы предпочтения, свойственные носителям какого-либо языка, находились выше в списке, или чтобы формат дат соответствовал локализации браузера.
• Метод i18n.detectLanguage() (en-US) используется для получения языка информации, введённой пользователем, и её форматирования.

В нашем примере notify-link-clicks-i18n , фоновый скрипт содержит следующие строки:

var title = browser.i18n.getMessage("notificationTitle");
var content = browser.i18n.getMessage("notificationContent", message.url);

Первая из них получает поле notificationTitle message из доступного файла messages.json, соответствующее наиболее подходящей локализации . Вторая строка похожа на первую, но в ней метод принимает URL в качестве второго параметра. Зачем? С помощью этого параметра мы указываем, на что нужно заменить заполнитель $URL$ в поле notificationContent message:

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

Объект "placeholders"  определяет все заполнители и то, откуда их нужно получать. Заполнитель "url" указывает, что информация о нем должна содержаться в $1 — первое значение, заданное внутри второго параметра getMessage(). Поскольку заполнитель называется "url",  $URL$ используется для его вызова внутри сообщения (то есть для заполнителя "name" нужно использовать $NAME$, и т. д.). Если вы хотите задать значения нескольких заполнителей, их можно передавать во второй аргумент i18n.getMessage() (en-US) в виде массива — массив [a, b, c] передаёт значения $1, $2 и $3, и т. д. внутрь messages.json.

Давайте посмотрим на пример: изначально сообщение notificationContent в файле en/messages.json такое:

You clicked $URL$.

Пусть эта ссылка указывает на https://developer.mozilla.org. После вызова i18n.getMessage() (en-US), содержание второго параметра становится доступно в messages.json в качестве значения $1, замещающего $URL$, так как это указано в заполнителе  "url". Таким образом, итоговое значение строки:

You clicked https://developer.mozilla.org.

Переменные ($1, $2, $3, и т. д.) можно вставлять напрямую в сообщения. Например, можно переписать объект "notificationContent" следующим образом:

"notificationContent": {
  "message": "You clicked $1.",
  "description": "Tells the user which link they clicked."
}

Этот метод может показаться более быстрым и простым, но другой способ (использование "placeholders") считается лучшей практикой. Это вызвано тем, что имена заполнителей (например "url") и примеры помогают понять, что означают заполнители — через неделю после написания кода Вы, наверное, забудете, что обозначают заполнители $1–$8, что менее вероятно, если заполнители именованы.

Значения заполнителей можно задавать вручную, если вы хотите, чтобы каждый раз это значение было одним и тем же, а не определялось переменной в коде. Например:

"mdn_banner": {
  "message": "For more information on web technologies, go to $MDN$.",
  "description": "Tell the user about MDN",
  "placeholders": {
    "mdn": {
      "content": "https://developer.mozilla.org/"
    }
  }
}

В этом примере мы сами задаём значение заполнителя, а не получаем его из переменной, такой как $1. Это может быть полезно, если сообщение очень сложное, и вы хотите разделить значения, чтобы сделать строки более читаемыми. К тому же, доступ к этим значениям можно получить внутри программы.

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

Локализации могут быть указаны с помощью кода языка, например fr или en. Они также могут содержать региональный код, например en_US или en_GB, описывающий региональный вариант языка. Когда вы запрашиваете строку у системы i18n, системы возвращает её используя следующий алгоритм:

1. Если для текущей локализации существует файл messages.json, содержащий требуемую строку, возвращается она.
2. Иначе,если текущая локализация — региональный вариант (например en_US) и существует файл messages.json для этого языка, но без указания региона  (например en), содержащий строку, возвращается она.
3. Иначе, если существует файл messages.json для default_locale, указанной в manifest.json, и этот файл содержит нужную строку, возвращается она.
4. В противном случае возвращается пустая строка.

Рассмотрим следующий пример:

• корневая-директория-расширения/
  • _locales
    • en_GB
      • messages.json
        • { "colorLocalised": { "message": "colour", "description": "Color." }, ... }
      en
      • messages.json
        • { "colorLocalised": { "message": "color", "description": "Color." }, ... }
    • fr
      • messages.json
        • { "colorLocalised": { "message": "couleur", "description": "Color." }, ...}

Пусть default_locale установлен как fr, а текущая локализация браузера — en_GB:

• Вызов getMessage("colorLocalised") вернёт "colour".
• Если бы в en_GB не было "colorLocalized", то вызов getMessage("colorLocalised"), вернул бы "color", а не "couleur".

Модуль i18n module предоставляет заранее определённые сообщения, которые можно вызвать таким же образом, как мы это делали в разделе Интернационализация manifest.json. Например:

__MSG_extensionName__

Заранее определённые сообщения используют такой же синтаксис, за исключением @@ перед именем сообщения, например:

__MSG_@@ui_locale__

Следующая таблица содержит различные заранее определённые сообщения:

Возвращаясь к нашему примеру, лучше было бы написать:

header {
  background-image: url(../images/__MSG_@@ui_locale__/header.png);
}

Теперь мы можем хранить изображения в директориях поддерживаемых локализаций — en, de, и т. д. — что выглядит логичней.

Давайте рассмотрим пример использования сообщений @@bidi_* в файле CSS:

body {
  direction: __MSG_@@bidi_dir__;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi_start_edge__: 0;
  padding-__MSG_@@bidi_end_edge__: 1.5em;
  position: relative;
}

Для языков, в которых текст читается слева направо, таких как английский, правила CSS, использующие заранее определённые сообщения, сверху задают такие значения:

direction: ltr;
padding-left: 0;
padding-right: 1.5em;

Для языков, читающихся справа налево, значения будут следующими:

direction: rtl;
padding-right: 0;
padding-left: 1.5em;

Начиная с Firefox 45, расширения могут быть временно установлены с диска — подробнее об этом написано в статье Loading from disk. Сделайте это и попробуйте протестировать наше расширение notify-link-clicks-i18n. Перейдите на одну из ваших любимых страниц и нажмите на ссылку, чтобы проверить, появляется ли сообщения, содержащее URL нажатой ссылки.

Затем измените локализацию Firefox на какую-либо поддерживающуюся расширением, которое вы хотите протестировать.

1. Откройте "about:config" в Firefox, и найдите параметр intl.locale.requested (обратите внимание на версию Firefox: в версиях до Firefox 59 этот параметр называется general.useragent.locale).
2. Если параметр существует, нажмите на него дважды (или нажмите Return/Enter), чтобы выбрать его, введите языковой код локализации, которую вы хотите протестировать и нажмите "OK" (или Return/Enter). Например, в нашем примере расширение поддерживает "en" (английский), "de" (немецкий), "nl" (голландский), and "ja" (японский). Вы также можете указать пустую строку ("") в качестве значения. В этом случае браузер выберет язык вашей ОС по умолчанию.
3. Если параметр intl.locale.requested не существует, нажмите правой кнопкой мыши на список параметров (или откройте контекстное меню при помощи клавиатуры), и выберите "New", а затем "String". Введите intl.locale.requested как имя настройки и, "de", "nl", и т. д. как значение, как это описано в шаге 2.
4. Найдите intl.locale.matchOS и, если параметр существует и равен true, дважды нажмите на него и установите на false.
5. Перезапустите браузер, чтобы изменения вступили в силу.

Ещё раз загрузите расширение с диска и протестируйте локализацию:

• Ещё раз откройте "about:addons" — теперь вы должны увидеть ваше расширение, его иконку, имя и описание на выбранном языке.
• Ещё раз протестируйте расширение. Для нашего примера, вам следовало бы посетить другую страницу и, нажав на ссылку, проверить, появляется ли сообщение на нужном языке.