国际化 V2
概览
国际化基于 @nuxtjs/i18n 实现，采用 opt-in（按需启用） 设计：
- 未启用 — Layer 仅把
@nuxtjs/i18n列为依赖，站点按单语言运行，界面文案取自内置翻译，路由不做本地化。 - 已启用 — 消费方在
nuxt.config.ts的modules加入@nuxtjs/i18n并配置i18n.locales后，自动激活多语言路由、按语言划分的内容集合、语言切换器与多语言 SEO。
无论是否启用，页面均通过统一入口 useMovkI18n() 访问当前语言、翻译函数与本地化路径，行为保持一致。
单语言界面
未启用 @nuxtjs/i18n 时，可通过 app.config.ts 指定界面语言，决定内置 UI 文案（目录标题、编辑链接、AI 助手等）使用哪种语言。
export default defineAppConfig({
i18n: {
locale: 'en' // 界面语言，默认 'zh-CN'
}
})
内置语言包当前提供 zh-CN、en 两种。此模式下 URL 不带语言前缀，内容目录保持单一结构。
多语言站点
1. 安装依赖
多语言需手动安装 @nuxtjs/i18n（Layer 不会自动拉取）：
npm install @nuxtjs/i18n
pnpm add @nuxtjs/i18n
yarn add @nuxtjs/i18n
bun add @nuxtjs/i18n
2. 配置 nuxt.config.ts
在 modules 中加入 @nuxtjs/i18n，并声明 defaultLocale 与 locales：
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' }
]
}
})
prefix_except_default：默认语言无前缀（/docs），其余语言带前缀（/en/docs）。无需手动设置 strategy。3. 组织内容目录
默认语言内容保持在 content/ 根目录原地不动，其余语言放入 content/{locale}/：
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。
新增一种语言需要同时满足两个条件，否则该语言在构建期会被过滤并输出告警：
- 存在对应翻译文件
{code}.json； - 存在对应内容目录
content/{code}/（默认语言除外，其内容位于content/根）。
UI 文案的解析顺序为 app.config.ts 覆盖 ?? 翻译文件。因此 app.config.ts 中的文案字段默认留空，由当前语言的翻译文件提供；如需覆盖单个词条，在 app.config.ts 中显式设置即可。
语言切换器
启用多语言后，站点头部自动显示语言切换器（LanguageSwitcher），以国旗 Emoji 呈现当前语言并列出全部有效语言，切换时跳转到对应语言的等价路径。
多语言 SEO
启用 i18n 且存在多个有效语言时，Layer 自动注入：
- 每种语言的
<link rel="alternate" hreflang="…">与x-default回退； - 当前语言的
og:locale； - 由
@nuxt/ui/locale驱动的<html lang/dir>。
浏览器语言重定向由 @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 | 当前语言的落地页集合名 |
useMovkI18n().t 为兼容未启用 i18n 场景的兼容入口，key 为普通字符串，无类型补全。已启用 i18n 时，layer 已开启 @nuxtjs/i18n 的 typed messages，需要 key 类型补全的消费方代码请直接使用原生 const { t } = useI18n()，它会自动识别 layer 内置与消费方自定义的全部 key。模板
如需开箱即用的多语言站点，可直接使用官方 i18n 模板：
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/i18n my-docs
该模板预置 zh-CN（默认）与 en 两种语言、对应内容目录与 @nuxtjs/i18n 配置。