i18n 全球化权威架构
深入探讨基于 URL 前缀的全球化方案与 SEO 同步逻辑。
PRID: 1612
VERIFIED
1 min read
🌐 i18n 全球化权威架构：物理路径隔离协议
核心哲学： 语言不仅是 UI 开关，更是物理资源路径。
在 Mouth Ship™ 中，我们实施 基于 URL 前缀的 i18n。这确保了您网站的每个语言版本对于搜索引擎来说都是一个独立的、可索引的资产，从而最大化您的全球覆盖范围。
1. “路径即上下文”策略
我们拒绝使用仅限 LocalStorage 或仅限 Cookie 的语言切换，因为爬虫是无状态的。
- URL 前缀： 所有路由都嵌套在
/$lang下（例如，/en/blog，/zh/blog）。 - 唯一事实来源： URL 是主状态。如果用户将 URL 从
/en修改为/zh，整个应用上下文会立即切换。 - 根路径检测仪式： 当用户访问
/时，引擎会执行优先级检查：localStorage('lng')(用户偏好)navigator.language(浏览器默认)siteConfig.defaultLocale(保底值) 然后执行 强力重定向 到相应的语言前缀。
2. 原子化翻译管理
为了防止“翻译膨胀”和合并冲突，我们在 src/locales/ 中使用了原子化文件夹结构。
文件夹层级：
src/locales/[lang]/common.ts: 共享 UI 元素（页脚、全局按钮）。src/locales/[lang]/nav.ts: 导航标签。src/locales/[lang]/home/[section].ts: 落地页的模块化章节（Hero、FAQ 等）。
注册流程：
所有模块都在 src/i18n.ts 中聚合。这个中心化的注册表允许通过 npm run check-i18n 进行自动化完整性检查。
3. SEO 与权威同步
URL 前缀模式的价值通过 <SEO /> 组件实现，该组件会自动注入：
- Hreflang 标签： 告诉 Google 哪些 URL 对应哪些语言，防止重复内容处罚。
- x-default： 指向未匹配地区的默认版本（通常为
/en/）。 - 动态 HTML Lang：
<html lang="...">属性实时更新以匹配路由，辅助屏幕阅读器和本地化搜索算法。
4. 开发 SOP：添加新内容
- 提取键值： 严禁在 JSX 中硬编码字符串。使用
const { t } = useTranslation('namespace')。 - 在源中定义： 将键添加到
src/locales/en/...。 - 镜像到目标： 立即将相同的键添加到
src/locales/zh/...。 - 运行审计： 在提交前执行
npm run check-i18n，确保生产环境中没有“缺失键 (Missing Key)”错误。
状态：工程协议已激活。此架构专为全球边缘分发而生。