Переводы

Локализация плагинов BDEngine: registerTranslations, namespace, языковые словари, gT, запасной текст и поведение при смене языка.

Плагин регистрирует свои строки через editorAPI.registerTranslations(), а читает их через глобальную функцию gT(). Переводы дополняют словари редактора в текущей сессии. Они не загружаются из каталога автоматически и не сохраняются в проект.

registerTranslations

const result = editorAPI.registerTranslations(namespace, translations = {});

Метод синхронный. namespace - непустая строка, общая для ключей вашего плагина. Используйте тот же уникальный идентификатор, что и в его метаданных. translations - объект, где ключ верхнего уровня задаёт язык, а значение является плоским словарём строк.

const result = editorAPI.registerTranslations('sample-panel', {
  'ru-RU': {
    title: 'Панель инструментов',
    open: 'Открыть панель',
  },
  'en-US': {
    title: 'Tool panel',
    open: 'Open panel',
  },
});

Поддерживаются языки редактора: en-US, ru-RU, zh-CN, zh-TW, ko-KR, de-DE. Коды нормализуются: например, en и ru принимаются как en-US и ru-RU. Для документации и плагинов удобнее использовать полные коды. Неподдерживаемый язык пропускается с предупреждением.

Значения словаря должны быть строками. Вложенный объект, массив или число вместо текста пропускается. Для группировки используйте полные строковые ключи, а не вложенные JSON-объекты.

Результат:

{ ok: true, added: 4, conflicts: 0 }

Поле	Смысл
`ok`	`false` при неверном namespace или неверном объекте `translations`. При корректной внешней форме - `true`, даже если отдельные языки или записи пропущены.
`added`	Количество принятых записей по всем языкам. Один ключ на двух языках даёт две записи. Повторная запись своего ключа тоже учитывается.
`conflicts`	Количество попыток использовать ключ ядра или ключ, уже принадлежащий другому namespace. Такие записи не добавляются.

Неверные языки и значения не увеличивают conflicts. Поэтому ok: true не означает, что приняты абсолютно все переданные строки: проверяйте счётчики и сообщения консоли во время разработки.

Простые и полные ключи

Если ключ не содержит точку, API добавляет префикс namespace.. Если содержит хотя бы одну точку, он используется как есть, без дополнительного префикса.

Namespace	Запись в словаре	Ключ для `gT()`
`sample-panel`	`title`	`sample-panel.title`
`sample-panel`	`sample-panel.window.title`	`sample-panel.window.title`
`sample-panel`	`window.title`	`window.title`

Последний вариант технически допустим, но легко конфликтует с другим кодом. Для вложенных по смыслу названий указывайте полный префикс плагина: sample-panel.window.title.

Редактор не разрешает перезаписывать занятые ключи ядра и другого namespace. Повторная регистрация ключа тем же namespace обновляет его значение. Это позволяет повторно применить словари при разработке, но требует уникального namespace у каждого плагина. Удаление неуказанных ключей при повторной регистрации не выполняется; публичного метода удаления словаря нет.

gT и fallback

const text = gT(key, fallback = key, options = {});

gT находится в window, отдельно от editorAPI. Вызовы gT(...) и window.gT(...) равнозначны. Используйте полный ключ после добавления namespace.

Поиск сначала использует язык редактора, затем английский en-US. Если перевод не найден и результат поиска совпадает с самим ключом, gT возвращает переданный fallback. Без запасной строки результатом будет ключ.

const title = gT('sample-panel.title', 'Tool panel');

Третий аргумент передаётся библиотеке локализации. Он позволяет подставлять значения в зарегистрированную строку:

editorAPI.registerTranslations('sample-panel', {
  'ru-RU': { selected: 'Выбрано объектов: {{count}}' },
  'en-US': { selected: 'Selected objects: {{count}}' },
});

const count = 3;
const text = gT(
  'sample-panel.selected',
  `Selected objects: ${count}`,
  { count },
);

Запасной текст возвращается напрямую: плейсхолдеры в нём отдельно не обрабатываются. Поэтому в примере fallback уже содержит значение count. Для обычных подписей вставляйте результат в textContent; наличие перевода не требует HTML-разметки.

Язык и обновление UI

Обычная смена языка в настройках редактора сохраняет выбранный язык и перезагружает редактор. Установленный плагин запускается заново, регистрирует словари и строит интерфейс уже с новым языком.

При этом gT() возвращает обычное значение в момент вызова. Ранее созданная кнопка с сохранённым текстом не обновляется автоматически при повторной регистрации строк. Если меняете словарь в текущей сессии, повторно вызовите gT() и обновите нужные DOM-элементы или пересоздайте своё окно.

Метод registerTranslations() не выполняет сетевые запросы за переводами. Включите словари в JavaScript плагина либо самостоятельно получите данные до регистрации. Регистрация должна произойти раньше создания подписей интерфейса. Общедоступного события bde:language-changed в этом механизме нет.

Минимальное применение

Пример регистрирует две локали и добавляет кнопку в панель инструментов. При нажатии локализованная строка выводится в консоль:

(() => {
  function init() {
    window.editorAPI.registerTranslations('sample-i18n', {
      'ru-RU': { message: 'Плагин готов к работе' },
      'en-US': { message: 'The plugin is ready' },
    });

    window.editorAPI.addButtonTool('icon-languages', () => {
      console.log(gT('sample-i18n.message', 'The plugin is ready'));
    });
  }

  if (window.editorAPI?.headPaint) init();
  else window.addEventListener('bde:started', init, { once: true });
})();

Полный сценарий с локализованными подписью кнопки и окном: «Локализовать интерфейс плагина».

Применить на практике

Локализовать интерфейс плагинаЛокализовать интерфейс плагина без конфликтов с другими расширениями.