Internationalization

Turn on multiple languages with @nuxtjs/i18n. This page covers installation, the content directory layout, per-locale collections, UI text overrides and hreflang SEO. Without it the site stays single-language, and you can still switch the UI language.
View source

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 by i18n.locale in app.config.
  • Multiple languages: once @nuxtjs/i18n is in modules and i18n.locales is configured in nuxt.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:

app/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

Configure nuxt.config.ts

Add @nuxtjs/i18n to modules and declare the default locale and the locale list:

nuxt.config.ts
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 _:

ContentDefault localeOther locales (e.g. en, zh-TW)Source
Docsdocsdocs_en, docs_zh_TWcontent/docs/**, content/{code}/docs/**
Homelandinglanding_encontent/index.md, content/{code}/index.md
Releasesreleasesreleases_encontent/releases.{md,yml}
Showcasetemplatestemplates_encontent/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:

  1. A translation file exists for it: the layer ships zh-CN and en, and your site provides i18n/locales/{code}.json for any other locale;
  2. The content directory content/{code}/ exists. The default locale lives at the root of content/ and is not checked.
terminal
[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.json containing only { "docs": { "tocTitle": "Contents" } } keeps every other key at its built-in value.
i18n/locales/ja.json
{
  "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:

app/app.config.ts
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 an x-default pointing to the first locale;
  • og:locale for the current locale (for example zh_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:

nuxt.config.ts
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:

terminal
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/i18n my-docs
Copyright © 2024 - 2026