--- title: "国际化" description: "Movk Nuxt Docs 内置基于 @nuxtjs/i18n 的多语言能力，采用 opt-in 设计：未配置时按单语言运行，配置后自动启用多语言路由、内容集合、语言切换器与多语言 SEO。本页介绍单语言界面配置、多语言站点搭建、内容目录约定与翻译文件管理。" seo_title: "Internationalization" seo_description: "Build multilingual Movk Nuxt Docs sites with @nuxtjs/i18n. Opt-in design with per-locale content collections, a language switcher, and hreflang SEO." canonical_url: "https://docs.mhaibaraai.cn/docs/getting-started/i18n" --- # 国际化 > Movk Nuxt Docs 内置基于 @nuxtjs/i18n 的多语言能力，采用 opt-in 设计：未配置时按单语言运行，配置后自动启用多语言路由、内容集合、语言切换器与多语言 SEO。本页介绍单语言界面配置、多语言站点搭建、内容目录约定与翻译文件管理。 ## 概览 国际化基于 [@nuxtjs/i18n](https://i18n.nuxtjs.org){rel="[\"nofollow\"]"} 实现，采用 **opt-in（按需启用）** 设计： - **未启用** — Layer 仅把 `@nuxtjs/i18n` 列为依赖，站点按单语言运行，界面文案取自内置翻译，路由不做本地化。 - **已启用** — 消费方在 `nuxt.config.ts` 的 `modules` 加入 `@nuxtjs/i18n` 并配置 `i18n.locales` 后，自动激活多语言路由、按语言划分的内容集合、语言切换器与多语言 SEO。 无论是否启用，页面均通过统一入口 `useMovkI18n()` 访问当前语言、翻译函数与本地化路径，行为保持一致。 ## 单语言界面 未启用 `@nuxtjs/i18n` 时，可通过 `app.config.ts` 指定界面语言，决定内置 UI 文案（目录标题、编辑链接、AI 助手等）使用哪种语言。 ```ts [app.config.ts] export default defineAppConfig({ i18n: { locale: 'en' // 界面语言，默认 'zh-CN' } }) ``` 内置语言包当前提供 `zh-CN`、`en` 两种。此模式下 URL 不带语言前缀，内容目录保持单一结构。 ## 多语言站点 ### 1\. 安装依赖 多语言需手动安装 `@nuxtjs/i18n`（Layer 不会自动拉取）： ```bash [npm] npm install @nuxtjs/i18n ``` ```bash [pnpm] pnpm add @nuxtjs/i18n ``` ```bash [yarn] yarn add @nuxtjs/i18n ``` ```bash [bun] bun add @nuxtjs/i18n ``` ### 2\. 配置 nuxt.config.ts 在 `modules` 中加入 `@nuxtjs/i18n`，并声明 `defaultLocale` 与 `locales`： ```ts [nuxt.config.ts] export default defineNuxtConfig({ extends: ['@movk/nuxt-docs'], modules: ['@nuxtjs/i18n'], i18n: { defaultLocale: 'zh-CN', locales: [ { code: 'zh-CN', name: '简体中文', file: 'zh-CN.json' }, { code: 'en', name: 'English', file: 'en.json' } ] } }) ``` > \[\!NOTE\] > > Layer 会强制将路由策略设为 > > prefix\_except\_default > > ： > > 默认语言无前缀 > > （ > > /docs > > ），其余语言带前缀（ > > /en/docs > > ）。无需手动设置 > > strategy > > 。 ### 3\. 组织内容目录 默认语言内容保持在 `content/` 根目录原地不动，其余语言放入 `content/{locale}/`： ```bash content/ ├── index.md # 默认语言（zh-CN）首页 ├── docs/ # 默认语言文档 → /docs/* │ └── 1.getting-started/ │ └── 1.index.md └── en/ # 英文内容 ├── index.md # 英文首页 → /en └── docs/ # 英文文档 → /en/docs/* └── 1.getting-started/ └── 1.index.md ``` Layer 会按语言自动生成内容集合：默认语言为 `docs` / `landing`，其余语言为 `docs_{code}` / `landing_{code}`（`code` 中的 `-` 替换为 `_`，如 `docs_zh_CN`）。 ## 翻译文件 界面文案（导航、按钮、AI 助手等）由翻译文件提供。内置 `zh-CN`、`en` 两种，分别位于包内 `i18n/locales/zh-CN.json` 与 `i18n/locales/en.json`。 新增一种语言需要同时满足两个条件，否则该语言在构建期会被过滤并输出告警： 1. 存在对应翻译文件 `{code}.json`； 2. 存在对应内容目录 `content/{code}/`（默认语言除外，其内容位于 `content/` 根）。 UI 文案的解析顺序为 **`app.config.ts` 覆盖 ?? 翻译文件**。因此 `app.config.ts` 中的文案字段默认留空，由当前语言的翻译文件提供；如需覆盖单个词条，在 `app.config.ts` 中显式设置即可。 ## 语言切换器 启用多语言后，站点头部自动显示语言切换器（`LanguageSwitcher`），以国旗 Emoji 呈现当前语言并列出全部有效语言，切换时跳转到对应语言的等价路径。 ## 多语言 SEO 启用 i18n 且存在多个有效语言时，Layer 自动注入： - 每种语言的 `` 与 `x-default` 回退； - 当前语言的 `og:locale`； - 由 `@nuxt/ui/locale` 驱动的 ``。 浏览器语言重定向由 `@nuxtjs/i18n` 的 `detectBrowserLanguage` 控制；如需固定首页语言，可在 `i18n` 配置中关闭它。 ## 统一入口 页面、组件与 Composable 通过 `useMovkI18n()` 访问国际化能力，在启用 / 未启用两态下行为一致： | 字段 | 说明 | | ------------------------ | --------------------------------- | | `isEnabled` | 是否启用了 `@nuxtjs/i18n` | | `locale` | 当前语言代码（响应式） | | `defaultLocale` | 默认语言代码 | | `locales` | 有效语言列表 | | `t(key, params?)` | 翻译函数，支持命名参数 | | `localePath(path)` | 转换为当前语言的本地化路径 | | `switchLocalePath(code)` | 获取切换到指定语言的路径 | | `docsRoot` | 文档根路径（`/docs` 或 `/{locale}/docs`） | | `docsCollection` | 当前语言的文档集合名 | | `landingCollection` | 当前语言的落地页集合名 | > \[\!NOTE\] > > useMovkI18n().t > > 为兼容未启用 i18n 场景的兼容入口，key 为普通字符串，无类型补全。已启用 i18n 时，layer 已开启 > > @nuxtjs/i18n > > 的 typed messages，需要 key 类型补全的消费方代码请直接使用原生 > > const { t } = useI18n() > > ，它会自动识别 layer 内置与消费方自定义的全部 key。 ## 模板 如需开箱即用的多语言站点，可直接使用官方 i18n 模板： ```bash npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/i18n my-docs ``` 该模板预置 `zh-CN`（默认）与 `en` 两种语言、对应内容目录与 `@nuxtjs/i18n` 配置。 ## Sitemap See the full [sitemap](/sitemap.md) for all pages.