---
title: "Internationalization"
description: "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."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/guide/i18n"
---
# 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.

## 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()`](https://docs.mhaibaraai.cn/en/docs/reference/composables/use-movk-i18n), 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`:

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

```bash [pnpm]
pnpm add @nuxtjs/i18n
```

```bash [npm]
npm install @nuxtjs/i18n
```

```bash [yarn]
yarn add @nuxtjs/i18n
```

```bash [bun]
bun add @nuxtjs/i18n
```

### Configure `nuxt.config.ts`

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

```ts [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](#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:

```text
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:

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.

```text [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.

```json [i18n/locales/ja.json]
{
  "docs": {
    "tocTitle": "目次",
    "copyPage": "ページをコピー"
  }
}
```

See the layer's [built-in translation file](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/i18n/locales/en.json) 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](https://docs.mhaibaraai.cn/en/docs/guide/navigation):

```ts [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](https://docs.mhaibaraai.cn/en/docs/guide/customization), 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:

```ts [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:

```bash [terminal]
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/i18n my-docs
```


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
