---
title: Internationalization
description: Built-in English and Russian UI strings, createI18n, overriding strings, adding a language, plural forms and the state of right-to-left support.
packages: ["@gotipe/i18n", "@gotipe/react", "@gotipe/block-editor"]
license: MIT
---

The strings of the ready UI come from two dictionaries. `@gotipe/i18n` carries the 148
strings that `@gotipe/react` and `@gotipe/ai-ui` draw (media, tables, code, embeds, formulas,
placeholders, AI controls) and a few shared words; `@gotipe/block-editor` carries the 322
strings of its own interface (menus, history, find, status line, alignment, fonts, atoms,
review, comments, page). Every key is used by a component. So an
app that uses only `@gotipe/react` does not load the block editor's strings. English
(`en`) is the default and Russian (`ru`) is built in, each with every key in both
dictionaries, and TypeScript checks key names. The document itself is never translated: only labels, placeholders,
tooltips and messages.

## Install

```sh
npm install @gotipe/i18n
```

`@gotipe/react` already depends on it.

```demo
i18n
```

## Choose a language

`PageEditor` takes the language directly: `locale="ru"`, or a ready dictionary in `i18n`.
`BlockEditor` and the components of `@gotipe/react` read it from `GoTipeI18nProvider`;
without a provider they use English. The accessible names of the document and of the menus
of `@gotipe/react` follow it too: `a11y.editorLabel` names `EditorContent` (and the
document of `BlockEditor`), `a11y.toolbarLabel` names `BubbleMenu` and `a11y.insertLabel`
names `FloatingMenu`; the `ariaLabel` prop of each wins over the dictionary.

```tsx title="RussianEditor.tsx"
import { BlockEditor } from "@gotipe/block-editor";
import type { GoTipeEditor } from "@gotipe/core";
import { GoTipeI18nProvider } from "@gotipe/react";

export function RussianEditor({ editor }: { editor: GoTipeEditor | null }) {
  return (
    <GoTipeI18nProvider locale="ru">
      <BlockEditor editor={editor} />
    </GoTipeI18nProvider>
  );
}
```

| Prop | Type | Description |
|---|---|---|
| `locale` | `string` | `"en"` or `"ru"`; another name falls back to English. |
| `i18n` | `I18n` | A dictionary from `createI18n`; wins over `locale`. |

`useGoTipeI18n()` returns the current `I18n` inside your own components. `PageEditor` sets
its own provider, so pass `locale` or `i18n` to it directly.

## createI18n

```ts title="i18n.ts"
import { createI18n, en, ru } from "@gotipe/i18n";

export const i18n = createI18n({ locale: "ru", locales: { en, ru } });

i18n.t("review.acceptAll"); // "Принять все"
i18n.t("table.resizeColumn", { index: 2 }); // "Ширина столбца 2"
i18n.plural("review.proposals", 5); // "5 предложений"
```

| Option | Type | Default | Description |
|---|---|---|---|
| `locale` | `string` | `"en"` | The current language. |
| `locales` | `Record<string, Locale>` | — | Dictionaries by name. Always include `en`, the fallback. A `Locale` has every key of `@gotipe/i18n` and may add block editor keys. |
| `fallbackLocale` | `string` | `"en"` | Used for keys missing in the current dictionary. |
| `defaultLocale` | `string` | — | Deprecated name of `locale`. |

| Member | Description |
|---|---|
| `t(key, params?)` | The string for `key`, with `{name}` placeholders replaced from `params`. |
| `plural(base, count, params?)` | The plural form of `base` for `count`; `{count}` is filled in. |
| `locale` | The current language. |
| `setLocale(name)` | Switch language; an unknown name logs a warning and changes nothing. |
| `addLocale(name, dictionary)` | Add a dictionary. |

A missing key falls back to the `fallbackLocale` dictionary, then to the key itself.

Inside `BlockEditor` and `PageEditor`, and in every component of `@gotipe/block-editor`, the
block editor puts its own strings under your `I18n` (`withBlockEditorStrings`): a string
your dictionaries have wins; otherwise its table of the current language, then its English
one. It recognizes a missing key by `t` returning the key itself, as `createI18n` does, so
an `I18n` of your own must do the same. `useBlockEditorI18n()` returns this `I18n` in your
components; `blockEditorEn` and `blockEditorRu` are the tables, typed `BlockEditorLocale`.

## Override strings

Spread a built-in dictionary and replace the keys you need. Keys of the block editor go
into the same dictionary; list only the ones you change, and the rest still come from
`@gotipe/block-editor`:

```ts title="strings.ts"
import { createI18n, en } from "@gotipe/i18n";

export const strings = createI18n({
  locale: "en",
  locales: {
    en: { ...en, "page.titlePlaceholder": "New page", "slashMenu.empty": "Nothing matches" },
  },
});

// <PageEditor markdown={file} i18n={strings} />
// <GoTipeI18nProvider i18n={strings}>…</GoTipeI18nProvider>
```

A few components also take labels directly: `SlashMenu` has `labels`, and `PageHead` has
`labels` and `placeholder`.

## Add a language

A `Locale` must have every key of `@gotipe/i18n`. Start from English, so untranslated keys
stay readable. For the block editor, add its English table too and translate what you need;
block editor keys you leave out fall back to its English table:

```ts title="de.ts"
import { blockEditorEn } from "@gotipe/block-editor";
import { type Locale, createI18n, en } from "@gotipe/i18n";

const de: Locale = {
  ...en,
  ...blockEditorEn,
  "toolbar.bold": "Fett",
  "slashMenu.empty": "Keine Treffer",
  "review.proposals.one": "{count} Vorschlag",
  "review.proposals.few": "{count} Vorschläge",
  "review.proposals.many": "{count} Vorschläge",
};

export const i18n = createI18n({ locale: "de", locales: { en, de } });
```

To switch language at runtime, create a new `I18n` (for example in `useMemo` keyed by the
locale). Calling `setLocale` on an instance already given to a provider does not re-render
the components.

The full list is the `TranslationKey` type: `BaseTranslationKey` ships in `@gotipe/i18n`,
`BlockEditorTranslationKey` in `@gotipe/block-editor`. Keys are grouped by prefix:
`toolbar.*`, `format.*`, `color.*` and `editor.*` for the formatting bubble; `slashMenu.*` and `slash.*` for the `/` menu and page blocks; `block.*`
for the handle and block menu; `table.*`, `media.*`, `code.*`, `callout.*`, `todo.*`,
`toggle.*`, `embed.*`, `math.*` for blocks; `placeholder.*` for empty blocks;
`review.*` and `comments.*` for review and `CommentSidebar`; `ai.*`, `a11y.*`, `page.*`,
`outline.*`, `theme.*`, `state.*` and `error.*` for the rest.

## Plural forms

The strings with plural forms (the `PluralKeyBase` type: `review.proposals`,
`review.staleCount`, `history.changed` and the status line's `status.*` counts) belong to
the block editor. Each has the keys `.one`, `.few` and `.many`. Russian, Ukrainian and Belarusian (`ru`, `uk`, `be`) use
their CLDR rules for one, few and many. Every other language uses `.one` for 1 and `.many`
for everything else, so `.few` is never chosen there.

## Right-to-left

> [!NOTE]
> Right-to-left is not supported yet. The stylesheets use physical left and right, and the
> block handle and menus are placed for left-to-right text. A few parts read the text
> direction (floating menus copy it, a new table column is scrolled into view either way),
> but no RTL layout is tested. The playground's i18n example shows a custom Arabic
> dictionary inside `dir="rtl"` as a preview only.

## Limitations

- The Vue adapter has no dictionaries, so its few words are English: the document's name
  "Document content" (`ariaLabel` of `EditorContent` gives another), a to-do's checkbox
  "Task completed" and a file without a name "File".
- The error toast shows a translated title and, under it, the error's own message, which
  is English. Only a stale suggestion (`PROPOSAL_STALE`) is said entirely in the interface's
  language.
- `defineLocale` registers a dictionary globally and is kept for compatibility; pass
  `locales` to `createI18n` instead.

## Related

- [Block editor](/docs/ui/block-editor) · [Page editor](/docs/ui/page-editor)
- [React](/docs/frameworks/react) · [Theming](/docs/ui/theming)
