ФреймворкJavaScript

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

Поддержка интернационализации для перевода строк интерфейса. Рантайм-мутатор i18n.update() меняет язык на месте.

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

normalizeLocale() служит предварительной проверкой для локали, которую вы не задали жёстко. i18n.update({ locale }) с неподдерживаемым тегом сохраняет текущую локаль и пишет предупреждение в консоль, а не выбрасывает исключение.

Обновлено 8 сент. 2026 г.Редактировать на GitHub

Как получить экземпляр редактора

Методы ниже вызываются на редакторе, созданном через new Blok(). Они доступны после того, как разрешится editor.isReady.

TypeScript

// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');

Методы

i18n.t(dictKey, vars?)

string

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

Когда использовать

Берёт строку интерфейса из активного словаря внутри инструмента, чтобы он локализовался вместе с редактором.

TypeScript

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)

i18n.has(dictKey)

boolean

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

Когда использовать

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

TypeScript

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

i18n.getEnglishTranslation(key)

string

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

Когда использовать

Возвращает английское значение независимо от локали. Используется для индексации контента в мультиязычном поиске.

TypeScript

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

i18n.getLocale()

string

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

Когда использовать

Возвращает код активной локали (например, 'en'), чтобы инструмент мог ветвиться по текущему языку редактора.

TypeScript

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

i18n.getDirection()

'ltr' | 'rtl'

Получить действующее сейчас направление текста. Оно выводится из активной локали, если не задано явное переопределение direction. Метод есть только на экземпляре редактора.

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

Когда использовать

Возвращает 'ltr' или 'rtl' для активной локали, чтобы интерфейс вокруг редактора зеркалился вместе с ним.

TypeScript

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

i18n.update({ locale?, messages?, direction? })

Promise<void>

Переключить язык в рантайме. 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 не принимается. Он лишь определяет запасной вариант при разрешении начальной локали.

Когда использовать

Меняет локаль и пользовательские переводы на лету и переименовывает интерфейс редактора на месте. Переключателю языка больше не нужно пересоздавать редактор и терять курсор, фокус и историю отмен.

TypeScript

// 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;
});

normalizeLocale(tag)

SupportedLocale | null

Из @bloklabs/core/locales. Приводит произвольный языковой тег BCP-47 к поддерживаемой локали Blok и возвращает null, когда тег не поддерживается. Тег может быть с регионом ('en-US'), с письменностью ('zh-Hant') или псевдонимом ('nb' в 'no', 'ckb' в 'ku').

Тот же нормализатор работает при определении по браузеру и при явных config.i18n.locale или i18n.update({ locale }). Поэтому null здесь означает ровно тот тег, который отверг бы update(): он сохраняет текущую локаль и пишет предупреждение в консоль, а не выбрасывает исключение.

TypeScript

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 });
}

loadLocale(code)

Promise<LocaleConfig>

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

TypeScript

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

const fr = await loadLocale('fr');

preloadLocales(codes)

Promise<void>

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

TypeScript

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

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

buildRegistry(codes)

Promise<LocaleRegistry>

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

TypeScript

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

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

getLocaleSync(code)

LocaleConfig | undefined

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

TypeScript

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

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

getDirection(code)

'ltr' | 'rtl'

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

TypeScript

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

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

Свойства

Свойство	Тип	Описание
`DEFAULT_LOCALE`	`SupportedLocale`	Из `@bloklabs/core/locales`. Код локали по умолчанию, `'en'`.
`ALL_LOCALE_CODES`	`readonly SupportedLocale[]`	Из `@bloklabs/core/locales`. Все 69 поддерживаемых кодов локалей. Из этого списка строят переключатель языка или передают его в `preloadLocales`.
`enLocale`	`LocaleConfig`	Из `@bloklabs/core/locales`. Английский словарь. Это единственная локаль, входящая в бандл по умолчанию, и запасной вариант для отсутствующих ключей.