> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/en/concepts/internationalization.md](/docs/manual/en/concepts/internationalization.md).

---
title: Internationalization
description: Create multi-language documentation with TockDocs built-in i18n support.
navigation:
  icon: i-lucide-globe
seo:
  description: Learn how to set up and manage multi-language documentation with TockDocs built-in i18n support.
  title: Internationalization
---

TockDocs supports internationalization in both of its content modes:

- **legacy mode** — locale-prefixed routes such as `/en/...` and `/zh/...`
- **knowledge-base mode** — KB-aware routes such as `/docs/manual/en/...` and `/docs/manual/zh/...`

## What TockDocs handles for you

- locale-aware content collections
- locale-aware route generation
- a language switcher for docs pages
- filtering locales that do not have actual content
- KB-aware locale behavior when different knowledge bases expose different locale sets

## Single-language sites

If your site is single-language and you are not using the full `@nuxtjs/i18n` module, you can still set the UI locale in `app.config.ts`:

```ts [app/app.config.ts]
export default defineAppConfig({
  tockdocs: {
    locale: 'zh',
  },
})
```

This is mainly for built-in UI strings and document language metadata.

## Multi-language setup with `@nuxtjs/i18n`

For real localized docs, configure `@nuxtjs/i18n` in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'zh', name: '简体中文' },
    ],
  },
})
```

::warning
TockDocs forces the docs routing strategy to `prefix` so localized docs routes stay explicit.
::

## Legacy mode content structure

In legacy mode, organize content by locale:

```bash
content/
├── en/
│   ├── index.md
│   └── 1.getting-started/
└── zh/
    ├── index.md
    └── 1.getting-started/
```

Typical routes:

- `content/en/index.md` → `/en`
- `content/zh/1.getting-started/3.installation.md` → `/zh/getting-started/installation`

## Knowledge-base mode content structure

In KB mode, locales live inside each knowledge base:

```bash
content/
├── site/
│   └── index.md
└── manual/
    ├── kb.yml
    ├── en/
    │   └── 1.getting-started/
    └── zh/
        └── 1.getting-started/
```

Example `kb.yml`:

```yaml [content/manual/kb.yml]
id: manual
title: Manual
defaultLocale: en
locales:
  - en
  - zh
entry: getting-started/installation
```

Typical routes:

- `/docs/manual/en/getting-started/installation`
- `/docs/manual/zh/getting-started/installation`

## Locale filtering

TockDocs only registers docs locales that are backed by real content.

That means:

- declaring a locale in `i18n.locales` is not enough on its own
- the corresponding content directory must also exist
- in KB mode, locale availability is evaluated per knowledge base

Example:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'zh', 'ja'],
  },
})
```

If your content only exists for `en` and `zh`, then `ja` is skipped for docs routing.

## Mixed locale counts in KB mode

KB mode supports different locale counts per knowledge base.

For example:

- `manual` may expose `en` and `zh`
- `chemistry` may expose only `zh`

In that case:

- the language switcher appears on multilingual KBs
- it stays hidden on single-locale KBs

## Default locale requirements

Always make sure your configured default locale actually exists in content:

- in legacy mode: `content/<defaultLocale>/...`
- in KB mode: `content/<kb>/<defaultLocale>/...`

If a docs locale is missing, TockDocs falls back to the KB or site default locale when possible.

## Starter template

If you want a preconfigured localized starter, use:

```bash [Terminal]
npx create-tockdocs my-docs -t i18n
```

That starter uses legacy mode with locale folders and `@nuxtjs/i18n` already configured.