---
title: "i18n API — перевод интерфейса редактора"
description: "Передача переводов для названий инструментов, подписей тулбара и строк доступности, которые рисует Blok."
source: https://blokeditor.com/ru/docs/i18n-api/
lastmod: 2026-09-07
---

Фреймворк JavaScript

Расширение и система Локализация

На этой странице i18n.t(dictKey, vars?)

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

Поддержка интернационализации для перевода строк интерфейса, а также рантайм-мутатор `i18n.update()`, который меняет язык на месте. Сам каталог локалей поставляется отдельной опубликованной точкой входа `@bloklabs/core/locales`: в бандл входит только английский, остальные 68 локалей загружаются по требованию, а `normalizeLocale()` — предварительная проверка для локали, которую вы не задали жёстко: `i18n.update({ locale })` с неподдерживаемым тегом сохраняет текущую локаль и выводит предупреждение в консоль вместо исключения.

[Редактировать на GitHub](https://github.com/JackUait/blok/blob/main/docs/src/components/api/api-data.ts)

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

Методы ниже вызываются на редакторе, созданном через 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

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

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

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

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 — с регионом (`'en-US'`), с письменностью (`'zh-Hant'`) или с псевдонимом (`'nb'` → `'no'`, `'ckb'` → `'ku'`) — до поддерживаемой локали Blok и возвращает `null`, когда тег не поддерживается. Тот же нормализатор работает при определении по браузеру и при явных `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`. Английский словарь — единственная локаль, входящая в бандл по умолчанию, и запасной вариант для отсутствующих ключей. |