统一语言处理并添加工具路由注册器 | Dev Logs

Date: 2026-01-11 15:30 Summary: 统一语言处理并添加工具路由注册器

[question]

1. 访问 http://localhost:8787/ja/ 下点击 http://localhost:8787/ja/tools/website-headers 会被重定向到 http://localhost:8787/zh/ja/tools/website-headers 并出现 404。
2. http://localhost:8787/ja/tools/website-headers 页面显示为英文而非日语。
3. markdown to html 工具没有支持目前的 10 国语言切换功能。
4. 是否可以将目前两个工具的语言控制合并，以便统一语言管理并便于后续扩展所有工具？
5. 要求实现“工具路由注册器”，把现有工具改用统一注册方式。

[try to solve] 问题分析：

• 中间件在进行 Accept-Language 协商和重定向时，检测路径是否显式带语言前缀的逻辑同时依赖“受支持语言”与“SITE_LANGS（启用语言列表）”。当路径前缀是受支持但未列为 SITE_LANGS 时，系统误以为路径未显式带语言，从而在协商后把选出的语言前缀再一次追加到已带前缀的路径上，产生类似 /zh/ja/... 的重定向并导致 404。

采取的修复与重构：

1. 修复显式语言前缀检测逻辑（避免错误重定向）

   • 修改 src/index.ts 中 getExplicitLangFromPath 的逻辑，使其只基于 isSupportedLang(seg) 判断路径是否显式带语言前缀（不再要求该语言在 SITE_LANGS 中）。
   • 结果：显式带语言前缀的 URL（如 /ja/...）不会再被协商中间件错误地重定向为 /zh/ja/...。

2. 保证语言渲染优先使用路径显式前缀

   • 调整工具路由：当路径显式带受支持语言时，使用该语言进行页面渲染（即使该语言未列入 SITE_LANGS），避免页面显示为默认语言或英文。

3. 统一语言工具函数

   • 将语言协商与辅助函数提取为中心模块 src/site/lang.ts，包含：DEFAULT_LANGS、getEnabledLangs、getFallbackLang、getDefaultLang、parseAcceptLanguage、pickLang、getExplicitLangFromPath、withLangPrefix、getLangFromPath、stripLangPrefix、langAlternatesForPath。
   • 目的是让不同路由/页面共享统一语言判断与行为。

4. 支持 markdown 工具显示 10 种语言

   • 修改 src/pages/markdownToHtmlPage.ts，让语言下拉切换与备用链接基于 supportedLangs（完整 10 语言），从而在页面头部显示所有语言切换项。

5. 实现并使用“工具路由注册器”

   • 新增 src/site/toolRegistrar.ts，导出 registerToolPage(app, toolName, renderFn)：该函数统一注册 /tools/<name> 与 /:lang/tools/<name> 路由，并使用集中语言逻辑来决定渲染语言或重定向。
   • 将 website-headers 与 markdown-to-html 的路由改为通过 registerToolPage 注册。这样新增工具时只需一处调用，可以保证语言处理的一致性。

验证步骤（本地）：

• 启动开发服务器：

npm run dev
# 或
wrangler dev

• 验证场景：
  • 访问 http://localhost:8787/ja/tools/website-headers 应直接以日语渲染（若 src/site/i18n/ja.ts 包含翻译条目）。
  • 访问 http://localhost:8787/tools/website-headers 将根据 Accept-Language 协商并可能重定向到合适语言前缀（预期行为）。
  • 打开 http://localhost:8787/tools/markdown-to-html，头部语言下拉应显示 10 种语言，并可切换到 ja 页面。

变更记录（代码变更）:

• 修改：src/index.ts（语言显式检测、路由改用注册器）
• 新增：src/site/lang.ts（集中语言工具函数）
• 新增：src/site/toolRegistrar.ts（统一工具页面注册器）
• 修改：src/pages/markdownToHtmlPage.ts（在头部语言下拉中显示 supportedLangs）
• 新增/修改日志：dev-logs/2026-01-11-fix-lang-redirect.md（记录首次重定向问题与修复）

后续建议：

• （推荐）将更多工具改为通过 registerToolPage 注册；这将使新增工具时语言行为一致。
• 添加小型集成或端对端测试覆盖语言前缀、Accept-Language 重定向与语言切换菜单，防止回归。
• 如果需要，我可以把当前改动整理成 commit（若尚未推送）并创建 PR，或立即把更多工具迁移到注册器。

[actions]

• 更新/新增文件：
  • src/index.ts
  • src/site/lang.ts
  • src/site/toolRegistrar.ts
  • src/pages/markdownToHtmlPage.ts
  • dev-logs/2026-01-11-fix-lang-redirect.md