国际化
配置 MuseMVP 的多语言路由、翻译加载与新增语言流程。
MuseMVP 基于 next-intl 实现全站国际化，涵盖落地页、控制台、文档与博客。本文介绍路由模型、翻译加载机制以及新增语言的步骤。
路由模型
src/i18n/routing.ts
src/config/index.ts
src/app/(landing-page)/[locale]/layout.tsx
| 配置项 | 说明 |
|---|---|
localePrefix | 默认 as-needed：默认语言（en）无 URL 前缀，其他语言带前缀（如 /zh） |
| 默认语言 | config.i18n.defaultLocale，通常为 en |
| 语言 Cookie | NEXT_LOCALE，用于持久化用户语言偏好 |
| 语言配置来源 | src/config/index.ts 的 config.i18n.locales |
as-needed 模式
在 as-needed 下，访问 / 等同于 /en，访问 /zh 为中文。有利于 SEO 与默认语言简洁 URL。
翻译加载机制
src/i18n/lib/messages.ts
src/i18n/translations/{en,zh}/*.json
- 加载入口：
src/i18n/lib/messages.ts - 模块化翻译目录：
src/i18n/translations/{en,zh}/*.json（如mvp.json、app.json等）
非默认语言会与默认语言消息合并，缺失字段自动回退到默认语言，避免空白展示。
新增语言步骤
在 config.i18n.locales 中新增语言元信息（label、appName、summary、headerMenuMap、footerConfig 等）。
新建对应语言翻译目录 src/i18n/translations/{locale}/ 及模块 JSON 文件。
补齐导航、页脚、文档别名等文案，确保 docsAlias、headerMenuMap、footerConfig.legal 等与现有语言结构一致。
验证路由跳转、metadata 输出及 sitemap 中是否包含新语言 URL。
// src/config/index.ts 示例
i18n: {
locales: {
en: { label: "English", ... },
zh: { label: "简体中文", ... },
ja: { label: "日本語", appName: "MuseMVP", ... }, // 新增
},
defaultLocale: "en",
}常见问题
排障建议
先核对环境变量、回调地址与密钥是否匹配，再排查业务逻辑。
| 现象 | 可能原因 |
|---|---|
| 翻译模块文件缺失导致运行时 fallback 警告 | 检查 src/i18n/translations/{locale}/*.json 是否存在且结构正确 |
| 菜单语言标签改了但具体文案未同步 | 确保 headerMenuMap、footerConfig 等与翻译文件一致 |
| 新语言路由可访问但 docs/blog 内容未覆盖 | Content Collections 与 docsSource 需支持多语言，检查 meta.{locale}.json 与 MDX 的 locale 后缀 |