Skip to content
Edit on GitHub

Internationalization

Built-in English and Russian UI strings, createI18n, overriding strings, adding a language, plural forms and the state of right-to-left support.

@gotipe/i18n@gotipe/react@gotipe/block-editorMIT

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

npm install @gotipe/i18n

@gotipe/react already depends on it.

Live editorSwitch the language
Loading the editor…

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.

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

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:

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:

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.