i18n API: перевод интерфейса Blok

Перевести ключ из глобального словаря, при необходимости подставив строковые или числовые значения.

const text = editor.i18n.t('toolNames.text');
console.log(text); // 'Text' (or translated string)

const limit = editor.i18n.t('tools.image.emptyMaxSize', { size: '10 MB' });
console.log(limit); // 'max 10 MB' (or translated string)

Проверить, существует ли перевод для заданного ключа.

if (editor.i18n.has('toolNames.text')) {
  const translation = editor.i18n.t('toolNames.text');
}

Получить английский перевод для ключа (используется для мультиязычного поиска).

const english = editor.i18n.getEnglishTranslation('toolNames.heading');
console.log(english); // 'Heading'

Получить код активной локали (например, 'en').

const locale = editor.i18n.getLocale();
console.log(locale); // 'en'

Получить действующее сейчас направление текста — выводится из активной локали, если не задано явное переопределение `direction`. Только на экземпляре редактора: `api.i18n`, который получают инструменты, несёт лишь `t`, `has`, `getEnglishTranslation` и `getLocale`, поэтому инструмент должен брать направление у хоста (из своей конфигурации или из события `i18n:changed`), а не вызывать этот метод.

if (editor.i18n.getDirection() === 'rtl') {
  // mirror your own chrome next to the editor
}

Переключить язык в рантайме. `config.i18n` в остальных случаях читается один раз при загрузке, поэтому хосту с переключателем языка приходилось пересоздавать редактор, чтобы поменять подписи, — теряя курсор, фокус, выделение и историю отмен. `update()` вместо этого меняет подписи на месте: без пересоздания, ничего не теряется. `locale` принимает любой поддерживаемый код или `'auto'`, чтобы заново выполнить определение по браузеру; `messages` накладывает переопределения хоста поверх словаря локали и автоматически применяется заново после каждой последующей смены локали (простое переключение локали никогда молча не отбрасывает ваши собственные строки); `direction` переопределяет направление, подразумеваемое локалью, — обычно это не нужно. Вызовы внутри сериализуются, поэтому лениво загружаемые чанки локалей не могут прийти не по порядку — побеждает последний вызов. Область действия: всё. Обрамление, которое строится по требованию (настройки блока, меню преобразования, уведомления, объявления для скринридеров), подхватывает новую локаль при следующем открытии; заранее проставленное обрамление (подписи панели инструментов и кнопки «плюс», подсказки, список тулбокса) получает новые подписи немедленно; а содержимое блоков — плейсхолдеры, подписи медиапанели, элементы управления ячейками, всё, что инструмент вычислил во время отрисовки, — перерисовывается из ваших данных, включая инструменты, которые ничего не знают о смене локали. Перерисовка для вас незаметна: `onChange` не срабатывает, прокрутка сохраняется, а курсор возвращается в тот блок, в котором был. Генерирует событие `i18n:changed` с `{ locale, direction }`. Доступен синхронно после создания — вызов, сделанный до `isReady`, применяется, как только редактор загрузится. `update()` и `getDirection()` доступны только на экземпляре редактора, а не на `api.i18n`, который получают инструменты (он несёт лишь `t`, `has`, `getEnglishTranslation` и `getLocale`), поэтому сторонний инструмент не может переключить локаль хоста. Адаптеры React/Vue/Angular управляют этим реактивно: измените проп/вход `i18n`, и редактор последует за ним на месте. Учтите, что `defaultLocale` не принимается — он лишь определяет запасной вариант при разрешении начальной локали.

// Host language switcher — no remount, caret and undo survive.
await editor.i18n.update({ locale: 'ru' });

// Locale plus your own overrides on top of it.
await editor.i18n.update({
  locale: 'fr',
  messages: { 'toolNames.text': 'Paragraphe' },
});

// Follow the browser again.
await editor.i18n.update({ locale: 'auto' });

editor.events.on('i18n:changed', ({ locale, direction }) => {
  document.documentElement.dir = direction;
});

Из `@bloklabs/core/locales`. Нормализует произвольный языковой тег BCP-47 — с регионом (`'en-US'`), с письменностью (`'zh-Hant'`) или с псевдонимом (`'nb'` → `'no'`, `'ckb'` → `'ku'`) — до поддерживаемой локали Blok и возвращает `null`, когда тег не поддерживается. Тот же нормализатор работает при определении по браузеру и при явных `config.i18n.locale` / `i18n.update({ locale })`, поэтому `null` здесь — ровно тот тег, который `update()` отверг бы: он сохраняет текущую локаль и предупреждает в консоли, а не выбрасывает исключение.

import { normalizeLocale } from '@bloklabs/core/locales';

// 'en-US' -> 'en'; null when the tag is not supported
const code = normalizeLocale(navigator.language);

if (code !== null) {
  await editor.i18n.update({ locale: code });
}

Из `@bloklabs/core/locales`. Загружает одну локаль по требованию. В бандл входит только английский — остальные 68 подгружаются, когда их запросят.

import { loadLocale } from '@bloklabs/core/locales';

const fr = await loadLocale('fr');

Из `@bloklabs/core/locales`. Загружает несколько локалей заранее — например, те, что предлагает ваш переключатель языка, — чтобы последующее переключение не ждало запроса.

import { preloadLocales } from '@bloklabs/core/locales';

await preloadLocales(['fr', 'de', 'ru']);

Из `@bloklabs/core/locales`. Загружает заданные коды и возвращает их вместе как `LocaleRegistry`.

import { buildRegistry } from '@bloklabs/core/locales';

const registry = await buildRegistry(['en', 'ru']);

Из `@bloklabs/core/locales`. Синхронно возвращает уже загруженную локаль или `undefined`, когда она ещё не загружена.

import { getLocaleSync, loadLocale } from '@bloklabs/core/locales';

const ru = getLocaleSync('ru') ?? await loadLocale('ru');

Из `@bloklabs/core/locales`. Направление текста для КОДА локали. Это не та же функция, что `editor.i18n.getDirection()`, которая не принимает аргументов и сообщает направление, используемое смонтированным редактором сейчас.

import { getDirection } from '@bloklabs/core/locales';

document.documentElement.dir = getDirection('ar'); // 'rtl'