Localization (i18n)

BlockNote is designed to be fully localized, with support for multiple languages. You can easily change the language of your editor or create custom translations.

Supported Languages

BlockNote supports the following languages out of the box:

Arabic (ar) - العربية
Chinese (Simplified) (zh) - 中文
Chinese (Traditional) (zh-tw) - 繁體中文
Croatian (hr) - Hrvatski
Dutch (nl) - Nederlands
English (en) - English
French (fr) - Français
German (de) - Deutsch
Hebrew (he) - עברית
Icelandic (is) - Íslenska
Italian (it) - Italiano
Japanese (ja) - 日本語
Korean (ko) - 한국어
Norwegian (no) - Norsk
Persian (fa) - فارسی
Polish (pl) - Polski
Portuguese (pt) - Português
Russian (ru) - Русский
Slovak (sk) - Slovenčina
Spanish (es) - Español
Turkish (tr) - Türkçe
Ukrainian (uk) - Українська
Uzbek (uz) - O'zbekcha
Vietnamese (vi) - Tiếng Việt

Basic Usage

To use a different language, import the desired locale and pass it to the dictionary option:

import { useCreateBlockNote, BlockNoteView } from "@blocknote/react";
import { fr } from "@blocknote/core/locales";

function FrenchEditor() {
  const editor = useCreateBlockNote({
    dictionary: fr,
  });

  return <BlockNoteView editor={editor} />;
}

The dictionary is selected when the editor is created. Pass [language] as the second argument to useCreateBlockNote to recreate it when the language changes, and key BlockNoteView by the language to reset its menus.

To preserve content, save the document outside the editor and pass it back as initialContent. Recreating the editor resets its undo history and selection. The localization example shows the complete implementation.

Customizing Text Strings

You can customize specific text strings by extending an existing dictionary:

import { useCreateBlockNote, BlockNoteView } from "@blocknote/react";
import { en } from "@blocknote/core/locales";

function CustomEditor() {
  const editor = useCreateBlockNote({
    dictionary: {
      ...en,
      placeholders: {
        ...en.placeholders,
        default: "Start typing your story...",
        heading: "Enter your title here",
        emptyDocument: "Begin your document",
      },
      slash_menu: {
        ...en.slash_menu,
        paragraph: {
          ...en.slash_menu.paragraph,
          title: "Text Block",
          subtext: "Regular text content",
        },
      },
    },
  });

  return <BlockNoteView editor={editor} />;
}

Dictionary Structure

The dictionary object contains translations for various parts of the editor:

Locale

The optional locale field selects the localized emoji names, categories, skin-tone names, and search terms used by the emoji picker. BlockNote's bundled dictionaries already set this field. When creating a custom dictionary, set it to the matching locale code; if it is omitted or unsupported, the emoji data falls back to English.

The picker interface strings use the same dictionary as the rest of BlockNote:

emoji_picker: {
  search: "Search",
  search_no_results: "No emoji found",
  loading: "Loading…",
}

Placeholders

Text that appears when blocks are empty:

placeholders: {
  default: "Enter text or type '/' for commands",
  heading: "Heading",
  bulletListItem: "List",
  numberedListItem: "List",
  checkListItem: "List",
  new_comment: "Write a comment...",
  edit_comment: "Edit comment...",
  comment_reply: "Add comment...",
}

Commands that appear when typing /:

slash_menu: {
  paragraph: {
    title: "Paragraph",
    subtext: "The body of your document",
    aliases: ["p", "paragraph"],
    group: "Basic blocks",
  },
  heading: {
    title: "Heading 1",
    subtext: "Top-level heading",
    aliases: ["h", "heading1", "h1"],
    group: "Headings",
  },
  // ... more menu items
}

UI Elements

Text for buttons, menus, and other interface elements:

side_menu: {
  add_block_label: "Add block",
  drag_handle_label: "Open block menu",
},
table_handle: {
  delete_column_menuitem: "Delete column",
  add_left_menuitem: "Add column left",
  // ... more table options
},
color_picker: {
  text_title: "Text",
  background_title: "Background",
  colors: {
    default: "Default",
    gray: "Gray",
    // ... more colors
  },
}

Integration with i18n Libraries

You can integrate BlockNote with popular i18n libraries like react-i18next or next-intl:

import { useCreateBlockNote, BlockNoteView } from "@blocknote/react";
import { useTranslation } from "react-i18next";
import * as locales from "@blocknote/core/locales";

function I18nEditor() {
  const { i18n } = useTranslation();

  const editor = useCreateBlockNote({
    dictionary: locales[i18n.language as keyof typeof locales] || locales.en,
  });

  return <BlockNoteView editor={editor} />;
}

Adding New Languages

To add support for a new language, you can:

Submit a Pull Request to the BlockNote repository with your translations
Create a custom dictionary in your application for immediate use

When creating translations, make sure to:

Set locale to the matching locale code so the emoji picker uses the appropriate localized data
Translate all text strings in the dictionary
Maintain the same structure as the English dictionary
Test the translations with different content types
Consider cultural differences in UI text

Examples

Basic Localization

GitHub

StackBlitz

import type { Block } from "@blocknote/core";import * as locales from "@blocknote/core/locales";import "@blocknote/core/fonts/inter.css";import { BlockNoteView } from "@blocknote/mantine";import "@blocknote/mantine/style.css";import { useCreateBlockNote } from "@blocknote/react";import { useRef, useState } from "react";type Language = keyof typeof locales;function isLanguage(value: string): value is Language {  return Object.hasOwn(locales, value);}// Human-readable names shown in the language picker.const languageNames = {  ar: "العربية",  de: "Deutsch",  en: "English",  es: "Español",  fa: "فارسی",  fr: "Français",  he: "עברית",  hr: "Hrvatski",  is: "Íslenska",  it: "Italiano",  ja: "日本語",  ko: "한국어",  nl: "Nederlands",  no: "Norsk",  pl: "Polski",  pt: "Português",  ru: "Русский",  sk: "Slovenčina",  tr: "Türkçe",  uk: "Українська",  uz: "Oʻzbekcha",  vi: "Tiếng Việt",  zh: "简体中文",  zhTW: "繁體中文",} satisfies Record<Language, string>;const languageKeys = Object.keys(locales)  .filter(isLanguage)  .sort((a, b) => languageNames[a].localeCompare(languageNames[b]));export default function App() {  const [language, setLanguage] = useState<Language>("en");  // Recreate the editor when the language changes, preserving its document.  const document = useRef<Block[] | undefined>(undefined);  const editor = useCreateBlockNote(    { dictionary: locales[language], initialContent: document.current },    [language],  );  return (    <div>      <label>        Language:{" "}        <select          value={language}          onChange={(event) => {            if (isLanguage(event.target.value)) {              setLanguage(event.target.value);            }          }}        >          {languageKeys.map((key) => (            <option key={key} value={key}>              {languageNames[key]}            </option>          ))}        </select>      </label>      {/* Remount the UI so menus also reset to the new language. */}      <BlockNoteView        key={language}        editor={editor}        onChange={() => {          document.current = editor.document;        }}      />    </div>  );}

/// <reference types="vite-plus/client" />

Custom Placeholders

GitHub

StackBlitz

import { en } from "@blocknote/core/locales";import "@blocknote/core/fonts/inter.css";import { BlockNoteView } from "@blocknote/mantine";import "@blocknote/mantine/style.css";import { useCreateBlockNote } from "@blocknote/react";export default function App() {  // We use the English, default dictionary  const locale = en;  // Creates a new editor instance.  const editor = useCreateBlockNote({    // We override the `placeholders` in our dictionary    dictionary: {      ...locale,      placeholders: {        ...locale.placeholders,        // We override the empty document placeholder        emptyDocument: "Start typing..",        // We override the default placeholder        default: "Custom default placeholder",        // We override the heading placeholder        heading: "Custom heading placeholder",      },    },  });  // Renders the editor instance using a React component.  return <BlockNoteView editor={editor} />;}

/// <reference types="vite-plus/client" />

import type { Block } from "@blocknote/core"; import * as locales from "@blocknote/core/locales"; import "@blocknote/core/fonts/inter.css"; import { BlockNoteView } from "@blocknote/mantine"; import "@blocknote/mantine/style.css"; import { useCreateBlockNote } from "@blocknote/react"; import { useRef, useState } from "react"; type Language = keyof typeof locales; function isLanguage(value: string): value is Language { return Object.hasOwn(locales, value); } // Human-readable names shown in the language picker. const languageNames = { ar: "العربية", de: "Deutsch", en: "English", es: "Español", fa: "فارسی", fr: "Français", he: "עברית", hr: "Hrvatski", is: "Íslenska", it: "Italiano", ja: "日本語", ko: "한국어", nl: "Nederlands", no: "Norsk", pl: "Polski", pt: "Português", ru: "Русский", sk: "Slovenčina", tr: "Türkçe", uk: "Українська", uz: "Oʻzbekcha", vi: "Tiếng Việt", zh: "简体中文", zhTW: "繁體中文", } satisfies Record<Language, string>; const languageKeys = Object.keys(locales) .filter(isLanguage) .sort((a, b) => languageNames[a].localeCompare(languageNames[b])); export default function App() { const [language, setLanguage] = useState<Language>("en"); // Recreate the editor when the language changes, preserving its document. const document = useRef<Block[] | undefined>(undefined); const editor = useCreateBlockNote( { dictionary: locales[language], initialContent: document.current }, [language], ); return ( <div> <label> Language:{" "} <select value={language} onChange={(event) => { if (isLanguage(event.target.value)) { setLanguage(event.target.value); } }} > {languageKeys.map((key) => ( <option key={key} value={key}> {languageNames[key]} </option> ))} </select> </label> {/* Remount the UI so menus also reset to the new language. */} <BlockNoteView key={language} editor={editor} onChange={() => { document.current = editor.document; }} /> </div> ); }

import type { Block } from "@blocknote/core";import * as locales from "@blocknote/core/locales";import "@blocknote/core/fonts/inter.css";import { BlockNoteView } from "@blocknote/mantine";import "@blocknote/mantine/style.css";import { useCreateBlockNote } from "@blocknote/react";import { useRef, useState } from "react";type Language = keyof typeof locales;function isLanguage(value: string): value is Language { return Object.hasOwn(locales, value);}// Human-readable names shown in the language picker.const languageNames = { ar: "العربية", de: "Deutsch", en: "English", es: "Español", fa: "فارسی", fr: "Français", he: "עברית", hr: "Hrvatski", is: "Íslenska", it: "Italiano", ja: "日本語", ko: "한국어", nl: "Nederlands", no: "Norsk", pl: "Polski", pt: "Português", ru: "Русский", sk: "Slovenčina", tr: "Türkçe", uk: "Українська", uz: "Oʻzbekcha", vi: "Tiếng Việt", zh: "简体中文", zhTW: "繁體中文",} satisfies Record<Language, string>;const languageKeys = Object.keys(locales) .filter(isLanguage) .sort((a, b) => languageNames[a].localeCompare(languageNames[b]));export default function App() { const [language, setLanguage] = useState<Language>("en"); // Recreate the editor when the language changes, preserving its document. const document = useRef<Block[] | undefined>(undefined); const editor = useCreateBlockNote( { dictionary: locales[language], initialContent: document.current }, [language], ); return ( <div> <label> Language:{" "} <select value={language} onChange={(event) => { if (isLanguage(event.target.value)) { setLanguage(event.target.value); } }} > {languageKeys.map((key) => ( <option key={key} value={key}> {languageNames[key]} </option> ))} </select> </label> {/* Remount the UI so menus also reset to the new language. */} <BlockNoteView key={language} editor={editor} onChange={() => { document.current = editor.document; }} /> </div> );}

Localization (i18n)

Supported Languages

Basic Usage

Dynamic Language Switching

Customizing Text Strings

Dictionary Structure

Locale

Placeholders

Slash Menu

UI Elements

Integration with i18n Libraries

Adding New Languages

Examples

Basic Localization

Custom Placeholders

On this page

Learn

Collaborate

Community

Legal & Theme