Internationalization
Two modes
Internationalization is opt-in:
- Single language (default): without
@nuxtjs/i18n, URLs have no locale prefix and UI text comes from the built-in translations, in the language set byi18n.localeinapp.config. - Multiple languages: once
@nuxtjs/i18nis inmodulesandi18n.localesis configured innuxt.config.ts, the layer turns on localized routes, per-locale content collections, the language switcher and hreflang.
In both modes, components and pages read the current locale, translations and localized paths through useMovkI18n(), so callers never need to check whether i18n is enabled.
Single-language sites
To switch only the UI language, set i18n.locale in app.config.ts:
export default defineAppConfig({
i18n: {
locale: 'en'
}
})
The default is zh-CN. Built-in translations currently cover zh-CN and en, and drive UI text such as the table of contents title, edit links, search and the AI assistant.
Multilingual sites
Install @nuxtjs/i18n
@nuxtjs/i18n is an optional peer dependency of the layer, so install it in your project:
pnpm add @nuxtjs/i18n
npm install @nuxtjs/i18n
yarn add @nuxtjs/i18n
bun add @nuxtjs/i18n
Configure nuxt.config.ts
Add @nuxtjs/i18n to modules and declare the default locale and the locale list:
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs'],
modules: ['@nuxtjs/i18n'],
i18n: {
defaultLocale: 'zh-CN',
locales: [
{ code: 'zh-CN', name: '简体中文' },
{ code: 'en', name: 'English' }
]
}
})
Only set code and name in locales, never file. The layer merges the built-in translations with matching files in your site's i18n/locales/ and registers the result (see Site translations); with file declared, @nuxtjs/i18n loads that file on its own and the build fails when it does not exist.
The layer pins the routing strategy to prefix_except_default, so there is no need to set strategy: the default locale has no prefix (/docs) and the others do (/en/docs).
Organize the content directory
Content for the default locale stays at the root of content/. Other locales live under content/{code}/ with the same structure:
content/
├── index.md # default locale home → /
├── docs/ # default locale docs → /docs/*
│ └── 1.getting-started/
│ └── 1.index.md
├── releases.yml # default locale releases page (optional)
└── en/
├── index.md # English home → /en
├── docs/ # English docs → /en/docs/*
│ └── 1.getting-started/
│ └── 1.index.md
└── releases.yml # English releases page (optional)
Content collections
The layer generates a set of Nuxt Content collections per locale. The default locale uses the base name; other locales get the locale code as a suffix, with - replaced by _:
| Content | Default locale | Other locales (e.g. en, zh-TW) | Source |
|---|---|---|---|
| Docs | docs | docs_en, docs_zh_TW | content/docs/**, content/{code}/docs/** |
| Home | landing | landing_en | content/index.md, content/{code}/index.md |
| Releases | releases | releases_en | content/releases.{md,yml} |
| Showcase | templates | templates_en | content/templates.{md,yml} |
When a locale has no releases or templates file, that route returns 404 for that locale only. In custom pages, use docsCollection, landingCollection and friends from useMovkI18n() to get the collection name for the current locale.
When a locale is valid
At build time the layer checks every entry in i18n.locales. A locale is used only when both conditions hold; otherwise it is skipped with a warning in the terminal:
- A translation file exists for it: the layer ships
zh-CNanden, and your site providesi18n/locales/{code}.jsonfor any other locale; - The content directory
content/{code}/exists. The default locale lives at the root ofcontent/and is not checked.
[movk-docs] 缺少内容目录 content/ja/,已跳过 locale "ja"
Site translations
Put {code}.json files in i18n/locales/ at your site root. At build time they are merged with the layer's built-in translations, with your values taking precedence:
- Add a locale: for example
i18n/locales/ja.json. Translate only the keys you need; missing keys fall back to the built-in English text. - Override built-in text: for example an
i18n/locales/en.jsoncontaining only{ "docs": { "tocTitle": "Contents" } }keeps every other key at its built-in value.
{
"docs": {
"tocTitle": "目次",
"copyPage": "ページをコピー"
}
}
See the layer's built-in translation file for the available keys. Restart the dev server after changing site translations.
UI text
UI text resolves as the value in app.config ?? the built-in translation for the current locale. Text fields in app.config (such as toc.title, aside.filter.placeholder and aiChat.texts.*) are empty by default so the translations apply; once set, that value is used in every locale.
For navigation text that differs per locale, write header.nav and docs.categories labels as objects keyed by locale code. See Navigation & Categories:
export default defineAppConfig({
header: {
nav: [
{ label: { 'zh-CN': '文档', 'en': 'Docs' }, to: '/docs/getting-started' }
]
}
})
Internal links get the current locale prefix automatically, so /docs/getting-started points to /en/docs/getting-started in English.
In your own components, the layer enables typed messages in @nuxtjs/i18n when i18n is on, so useI18n().t completes every built-in and custom key. useMovkI18n().t works in both modes but has no key types.
Language switcher
When i18n is enabled with at least two valid locales, a language switcher (LanguageSwitcher) appears on the right of the header. It lists every valid locale and navigates to the same page in the target locale. It is part of the override contract, so a component with the same name replaces it.
Multilingual SEO
With at least two valid locales, useLocaleSeo() adds to every page:
- a
<link rel="alternate" hreflang="…">for each locale, plus anx-defaultpointing to the first locale; og:localefor the current locale (for examplezh_CN).
<html lang> and dir are set by @nuxt/ui's locale for the current language. @nuxtjs/sitemap splits the sitemap per locale, with /sitemap_index.xml as the entry.
Browser language redirection on the first visit is controlled by detectBrowserLanguage in @nuxtjs/i18n. Turn it off to keep the home page in a fixed language:
export default defineNuxtConfig({
i18n: {
detectBrowserLanguage: false
}
})
i18n template
To start a bilingual site right away, use the i18n template. It comes with zh-CN (default) and en, the matching content directories and configuration:
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/i18n my-docs
Pages & Layouts
Besides docs pages, the layer generates the landing page, a releases page and a showcase page from files in the content directory, and you can write any Vue page in app/pages. This page covers when each built-in route is generated and its content format, header and footer switches for custom pages, and the built-in layouts.
OG Images
Every docs page gets a social sharing image (OG image) generated at build time. This page covers the fields the built-in template reads, generating images for custom pages, replacing the template, and what happens when the feature is off.