Internationalization (i18n)

Doculite has built-in multi-language support powered by next-intl. English is the default locale with no URL prefix. Other locales use a prefix like /vi/docs/page.

How It Works

• Content translations use a filename suffix pattern: page.vi.mdx alongside page.mdx
• Sidebar labels use _meta.vi.json alongside _meta.json
• UI strings (search, banners) are translated via JSON message files
• Untranslated pages automatically fall back to English with an info banner
• Search results filter by the current locale

Adding a New Locale

export const SUPPORTED_LOCALES = ["en", "vi", "ja"] as const;
 
export const LOCALE_LABELS: Record<Locale, string> = {
  en: "English",
  vi: "Tiếng Việt",
  ja: "日本語",
};

{
  "common": {
    "search": "ドキュメントを検索...",
    "searchShort": "検索...",
    "noResults": "結果が見つかりません。"
  },
  "i18n": {
    "switchLanguage": "言語",
    "untranslatedBanner": "このページはまだ{language}では利用できません。英語版を表示しています。"
  },
  "footer": {
    "builtWith": "Doculiteで構築。"
  }
}

{
  "getting-started": { "title": "はじめに", "order": 1 },
  "writing-content": { "title": "コンテンツ作成", "order": 2 },
  "components": { "title": "コンポーネント", "order": 3 }
}

content/docs/
  index.mdx          # English (default)
  index.ja.mdx       # Japanese translation
  getting-started/
    installation.mdx
    installation.ja.mdx

Creating Translated Content

Each translation is a separate MDX file with the locale suffix before .mdx:

page.mdx        → English (default)
page.vi.mdx     → Vietnamese
page.ja.mdx     → Japanese

The frontmatter structure is the same. Translate the title and description:

---
title: Cài đặt
description: Hướng dẫn cài đặt và thiết lập Doculite.
order: 1
---
 
Your translated content here...

Sidebar Labels

Each directory can have locale-specific sidebar labels via _meta.{locale}.json:

The sidebar always shows all pages, including untranslated ones. Untranslated pages link to the English fallback with a banner.

Language Switcher

A globe icon in the header opens a dropdown to switch between available locales. The switcher preserves the current page path — navigating from /docs/page to /vi/docs/page.

Search

The Cmd+K / Ctrl+K search only shows results for the current locale. If you're browsing Vietnamese docs, only Vietnamese-translated pages appear in search results.

SEO

Doculite automatically adds hreflang meta tags to every doc page, telling search engines about available translations:

<link rel="alternate" hreflang="en" href="https://example.com/docs/page" />
<link rel="alternate" hreflang="vi" href="https://example.com/vi/docs/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/docs/page" />

The x-default tag always points to the English version.

URL Structure

English has no prefix. All other locales are prefixed with their locale code.