Локализовать интерфейс плагина

Добавим русский и английский текст кнопке и окну. Плагин регистрирует собственные словари через editorAPI.registerTranslations() и читает строки глобальной функцией gT(). Язык выбирает пользователь редактора.

До начала выберите уникальный namespace плагина. Скачать полный пример translations.js. После установки нажмите кнопку с иконкой языков на панели инструментов.

Выбрать пространство имён

Используем namespace my-plugin и простые ключи title и message. При регистрации они превратятся в my-plugin.title и my-plugin.message. Этот префикс отделяет строки плагина от редактора и других расширений.

Важная деталь: ключ, который уже содержит точку, принимается как полный. Например, window.title останется window.title, а не станет my-plugin.window.title. Чтобы сделать несколько групп, укажите полный ключ my-plugin.window.title сами или используйте простые ключи вроде windowTitle.

Namespace словаря удобно делать таким же, как @namespace файла, но передаётся он отдельным аргументом. Это не игровой тег модели и не идентификатор экспорта.

Зарегистрировать словари

const namespace = 'my-plugin';
const result = window.editorAPI.registerTranslations(namespace, {
  'ru-RU': {
    title: 'Моё окно',
    message: 'Плагин готов к работе.',
  },
  'en-US': {
    title: 'My window',
    message: 'The plugin is ready.',
  },
});

console.log(result); // {ok: true, added: 4, conflicts: 0} для этих четырёх записей.

Внешние ключи - языки; внутренние словари плоские и содержат строки. Не передавайте вложенный объект window: {title: ...}. Для примера достаточно ru-RU и en-US; редактор нормализует также поддерживаемые псевдонимы ru и en.

Регистрируйте переводы до создания интерфейса. Существующие строки ядра и строки другого владельца защищены от перезаписи. Конфликтующие ключи пропускаются и увеличивают conflicts. Повторная регистрация своих ключей тем же namespace обновляет значения. added считает добавленные записи словарей по языкам, не только уникальные имена ключей.

ok: true означает, что вызов прошёл общую проверку, но не гарантирует принятие каждой записи. Некорректные языки, словари или значения могут быть пропущены с предупреждением в консоли. Следите за added, conflicts и содержимым своих словарей.

Подробности результата и нормализации: контракт registerTranslations.

Использовать gT

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

const t = (key, fallback) => window.gT(`my-plugin.${key}`, fallback);

const button = window.editorAPI.addButtonTool('icon-languages', () => {
  const panel = window.editorAPI.createWindow(
    t('title', 'My window'), 'my-plugin.window', 'icon-languages',
    520, 300, 320, 220
  );
  const message = document.createElement('p');
  message.textContent = t('message', 'The plugin is ready.');
  panel.container.append(message);
});
button.title = t('title', 'My window');
button.setAttribute('aria-label', button.title);

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

Для текста внутри собственного DOM используйте textContent, как в примере. Полный скачиваемый файл также не создаёт второе окно при повторном нажатии: он фокусирует существующее. Для теста fallback в нём намеренно вызывается отсутствующий ключ bde.docs.translations.missing с понятной английской резервной строкой.

Работа с кнопками и окнами: справочник интерфейса.

Проверить язык и отсутствующий перевод

1. Установите пример и откройте его окно в русской локали. Заголовок и основное сообщение должны быть русскими, последняя строка показывает намеренный fallback.
2. Переключите язык редактора на английский. Текущая реализация смены языка перезагружает редактор; после загрузки установленный плагин регистрирует словари заново.
3. Откройте окно повторно и проверьте английские строки и подпись кнопки.
4. Для проверки языкового fallback в собственной копии уберите только русское значение message, сохранив английское. В русской локали должна использоваться английская строка. Затем удалите этот ключ из обоих словарей и проверьте fallback аргумента gT.
5. Проверьте, что conflicts равен нулю. При ненулевом значении исправьте полные ключи или выберите свой namespace, вместо попытки перезаписать чужой словарь.

Созданные DOM-узлы не связаны с ключами автоматически: gT() возвращает строку в момент вызова. При изменении словарей уже вставленный textContent сам не обновится; если нужен такой сценарий, плагин должен прочитать строку и назначить её повторно.

Публичного удаления зарегистрированного словаря сейчас нет. Полный пример убирает свою кнопку и окно при повторном выполнении через собственную dispose(), но это локальная договорённость примера, а не автоматический lifecycle редактора. Удаление плагина и перезагрузка завершают его использование вместе с текущими словарями.

Формат словарей, порядок fallback и смена языка сверены с publicFunctions.js, Locale.js и localeConfig.js. Переводы остальных языков автор плагина добавляет сам.