Boltdocs Logo
GuidesIntegrationsAPIPluginsComponentsReleases

Internationalization (i18n)

Set up multilingual documentation with folder-based locale routing, automatic fallbacks for untranslated pages, and RTL support.

Boltdocs has first-class support for multilingual documentation. Locales are driven by folder conventions — place your translated pages in locale-named subfolders and Boltdocs handles routing, fallbacks, and locale switching automatically.

Quick StartLink

Step 1: Add i18n to your configurationLink

ts
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
  },
})

Step 2: Create locale foldersLink

Create a subfolder for each non-default locale inside docs/:

sh
mkdir docs/es docs/fr

Step 3: Add translated pagesLink

text
docs/
├── getting-started.md          # English (default)
├── es/
│   └── getting-started.md      # Spanish translation
└── fr/
    └── getting-started.md      # French translation

That's it! The locale selector (if your layout includes one) and URL structure are configured automatically.

Automatic FallbacksLink

If a translated page doesn't exist for a locale, Boltdocs automatically generates a fallback route that serves the default locale's content. The URL still keeps the locale prefix so the selector works correctly:

  • /docs/es/advanced will serve the advanced.md in English if docs/es/advanced.md doesn't exist.
Note

Fallback routes are generated at build time. End users reach the page without any error, though the content will be in the default language. You can detect this in a custom layout using the useI18n() hook to show a "Translation pending" banner.

i18n Configuration ReferenceLink

BoltdocsI18nConfigLink

PropertyTypeRequiredDescription
defaultLocalestring✓The locale code for your main language (e.g. 'en'). Pages at the root of docs/ (not inside a locale folder) belong to this locale.
localesstring[] | Record<string, string>✓All supported locale codes. Can be an array of codes or a map of { code: label } pairs.
localeConfigsRecord<string, LocaleConfig>—Per-locale display and behavior settings. See LocaleConfig below.

LocaleConfigLink

PropertyTypeDefaultDescription
labelstringLocale codeHuman-readable name for this locale (e.g. 'English', 'Español').
direction'ltr' | 'rtl''ltr'Text direction. Set to 'rtl' for right-to-left languages like Arabic or Hebrew.
htmlLangstringLocale codeThe value of the lang attribute for the <html> tag (e.g. 'en-US', 'ar').
calendarstring—The calendar system to use for date formatting (e.g. 'islamic', 'buddhist').

Complete Configuration ExampleLink

boltdocs.config.ts
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: {
      en: 'English',
      es: 'Español',
      ar: 'العربية',
    },
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',
        htmlLang: 'en-US',
      },
      es: {
        label: 'Español',
        direction: 'ltr',
        htmlLang: 'es-ES',
      },
      ar: {
        label: 'العربية',
        direction: 'rtl',
        htmlLang: 'ar',
      },
    },
  },
})

RTL SupportLink

Setting direction: 'rtl' on a locale tells Boltdocs to flip the layout for that locale. The sidebar moves to the right, navigation arrows are mirrored, and dir="rtl" is set on the <html> element.

Translating Theme StringsLink

Properties like theme.title, theme.description, and navbar labels support per-locale key maps, letting you translate the UI along with the content:

boltdocs.config.ts
export default defineConfig({
  theme: {
    title: {
      en: 'My Project',
      es: 'Mi Proyecto',
      ar: 'مشروعي',
    },
    navbar: [
      {
        label: { en: 'Docs', es: 'Documentación', ar: 'المستندات' },
        href: '/docs',
      },
    ],
  },
})
Jesús Alcalá
Last updated on October 18, 2026

Was this page helpful?