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:

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:

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

Legacy mode content structure

In legacy mode, organize content by locale:

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:

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

Example 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:

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
• parser may expose only en

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:

npx create-tockdocs my-docs -t i18n

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