多语言说明手册

本站点通过一份统一语言配置支持 29 个语言/地区版本。

支持语言

当前语言码：

zh, en, ru, es, pt-br, de, ko, ja, fr, pl, zh-tw, tr, th, es-419, uk, it, cs, hu, pt, sv, nl, vi, da, id, fi, ro, no, el, bg, ar。

地区规则：

• zh 表示简体中文。
• zh-tw 表示繁体中文，同时覆盖台湾、香港、澳门。
• es 表示西班牙语（西班牙）。
• es-419 表示西班牙语（拉丁美洲）。
• pt 表示葡萄牙语（葡萄牙）。
• pt-br 表示葡萄牙语（巴西）。
• ar 是从右到左书写语言，运行时会设置 document.documentElement.dir = "rtl"。

当前机制

• 语言配置在 .vitepress/shared/locales.ts。
• 前端当前语言状态在 .vitepress/theme/composables/useCurrentLanguage.ts。
• VitePress 的多语言 locale 由 languageCodes 和 gameIds 自动生成，不需要手写每一种语言的 locale。
• 用户手动选择的语言会保存到 localStorage，键名是 guide-site-language。
• 根首页 / 不跳转，会根据当前语言动态展示首页文案和游戏入口。
• 游戏页面路径格式是 /games/subnautica-2/{language}/guides/，切换语言时只替换路径中的语言段。

浏览器语言弱匹配

匹配顺序是：先精确匹配，再按主语言回退。

• pt-BR 匹配 pt-br，其他 pt-* 匹配 pt。
• es-419 匹配 es-419，其他 es-* 匹配 es。
• zh-TW、zh-HK、zh-MO、zh-Hant 匹配 zh-tw。
• zh-CN、zh-Hans、其他 zh-* 匹配 zh。
• nb、nn 匹配 no。
• 不支持的语言回退到 en。

新增语言

1. 在 .vitepress/shared/locales.ts 增加语言。

   • 在 languages 里加一项。
   • 在 games['subnautica-2'].description 里加对应语言的游戏描述。
   • 在 aliases 里补浏览器可能上报的语言码。

2. 为每个游戏补内容目录。

   • 必备页面：
     • games/subnautica-2/{lang}/index.md
     • games/subnautica-2/{lang}/guides/index.md
     • games/subnautica-2/{lang}/problems/index.md
   • 详情页可以后续逐步翻译。只有对应语言下存在同 slug 的详情页时，同页切换才会进入完整翻译页。

3. 更新翻译工具。

   • 在 tools/video-guide-generator/translate_guide.py 的 LANGUAGE_NAMES 里加入语言名。
   • 如果某种语言需要特殊校验，再补对应验证规则。

翻译耗时优化

建议使用“缓存 + 分批 + 多语言并发”：

python tools\video-guide-generator\translate_guide.py 7641058917526654246-fa0221a286 `
  --site-root sites\guide-site `
  --game-id subnautica-2 `
  --source-lang zh `
  --targets en ru es pt-br de ko ja fr `
  --step-batch-size 10 `
  --jobs 4

推荐发布节奏：

• 第一阶段：先上线 29 种语言的 UI、首页、索引页。
• 第二阶段：优先翻译重点详情页：en, ru, es, pt-br, de, ko, ja, fr。
• 第三阶段：后台慢慢补齐剩余语言详情页。

参数建议：

• .cache/translation 是翻译缓存，同一 prompt 命中缓存时不会重新调用模型。
• --step-batch-size 8-12 能减少长攻略的请求次数。
• --jobs 3-5 比较稳，太高可能触发 API 限流。
• 多目标语言翻译时，单个语言失败会单独报错，不会掩盖其他语言结果。

本地验证

构建站点：

npm run docs:build

翻译脚本 dry-run：

python tools\video-guide-generator\translate_guide.py 7641058917526654246-fa0221a286 --target es --dry-run
python tools\video-guide-generator\translate_guide.py 7641058917526654246-fa0221a286 --targets en es pt-br --dry-run

手动检查：

• / 首页语言按钮能显示全部 29 种语言。
• /games/subnautica-2/en/guides/ 切换到葡萄牙语（巴西）后进入 /games/subnautica-2/pt-br/guides/。
• es 和 es-419 不互相混淆。
• 浏览器语言 zh-TW、zh-HK 会匹配到 zh-tw。
• ar 页面方向是 RTL，导航和按钮不重叠。
• 生成的 Markdown 和 locales.ts 没有乱码。

常见问题

• 语言按钮不显示：检查 .vitepress/theme/Layout.vue 是否仍然渲染 LanguageSwitcher。
• 首页不随语言变化：检查 index.md 是否渲染 <HomeLanguageContent />。
• 新语言构建后不存在：检查 languages 里是否有该语言，并确认内容索引页已经创建。
• 路径切换失败：检查目录语言码是否和 languages 里的语言码完全一致。
• 出现乱码：把受影响文件重新保存为 UTF-8，避免使用会按系统旧代码页写文件的命令。