Internationalization (i18n)

Add multi-language support to your documentation

zudo-doc supports multiple languages using Astro’s built-in i18n routing.

How It Works

• English (default): /docs/... — content lives in src/content/docs/
• Japanese: /ja/docs/... — content lives in src/content/docs-ja/

The language switcher in the site header lets users toggle between available languages.

Settings-Based Locale Configuration

Locales are configured in src/config/settings.ts:

export const settings = {
  // ...
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
};

For each locale entry, zudo-doc automatically:

• Creates an Astro content collection (docs-{code})
• Registers the locale in Astro’s i18n routing
• Generates the appropriate page routes
• Adds the locale to the language switcher

This means adding a new locale only requires a settings entry and a content directory — no manual collection or route setup needed.

Directory Structure

Localized docs mirror the English directory structure:

src/content/
├── docs/
│   ├── getting-started/
│   │   ├── introduction.mdx
│   │   └── installation.mdx
│   └── guides/
│       └── configuration.mdx
└── docs-ja/
    ├── getting-started/
    │   ├── introduction.mdx
    │   └── installation.mdx
    └── guides/
        └── configuration.mdx

Language Switcher

The language switcher appears in the header’s right edge. It shows the current language code (EN or JA) and a link to switch to the alternate language. The switcher automatically computes the alternate URL by adding or removing the /ja/ prefix.

UI Translation Keys

zudo-doc uses a translation key system for built-in UI strings. Keys are organized by namespace:

• nav.* — Header navigation labels (e.g., nav.gettingStarted, nav.guides)
• toc.* — Table of contents labels
• search.* — Search dialog text
• code.* — Code block UI (copy button, etc.)
• doc.* — Document-level UI (edit link, metadata labels, etc.)

These keys allow the entire UI (not just content) to be localized across all configured languages.

Astro Configuration

i18n routing is configured in astro.config.ts:

i18n: {
  defaultLocale: "en",
  locales: ["en", ...Object.keys(settings.locales)],
  routing: {
    prefixDefaultLocale: false,
  },
},

With prefixDefaultLocale: false, English pages are served without a language prefix (/docs/...) while Japanese pages use the /ja/ prefix (/ja/docs/...).

Adding a New Language

To add a new language (e.g., Korean):

1. Add the locale to settings.ts:

   locales: {
     ja: { label: "JA", dir: "src/content/docs-ja" },
     ko: { label: "KO", dir: "src/content/docs-ko" },
   },

2. Create a content directory: src/content/docs-ko/
3. Mirror the English directory structure with translated files
4. Add a new page route at src/pages/ko/docs/[...slug].astro (copy from an existing locale route)
5. Add UI translations for the new locale