Arthur Koba
4.9 KiB
运行时语言与国际化
运维输出与界面文案
Server、Agent、后台任务、安装/卸载脚本以及浏览器 PoW 调试日志的固定文案使用英文。语言切换不会改变控制台日志或 OTel 异常信息，便于跨语言检索和排障。任务参数、文件名、用户配置和第三方错误保留原文，可能包含中文。
前端继续使用 next-intl，以 en 为默认语言，保留 zh-CN 语言资源。当前阶段先整理英文基准文案并移除运行时中文硬编码，中文译文的进一步审校和统一验证安排在后续阶段。文案维护在 frontend/messages/fragments，通过 node scripts/merge-i18n-fragments.mjs 生成主消息包。技术示例与 HTML 使用原始消息读取，避免把代码中的花括号当作 ICU 参数。
语言选择器始终从各语言自己的资源读取名称：English 与 中文，不随当前界面语言翻译语言名称。
不在 React 渲染上下文中的浏览器代码（如网络异常和纯表单工具）通过 frontend/i18n/runtime.ts 调用同一套 next-intl 文案。消息在使用时解析语言，不在模块导入时固定语言。API 客户端发送当前界面语言的 Accept-Language。
服务端展示边界
pkg/i18n/locales 保留内置服务端文案的英文和中文版本，英文同时是运行时源码中的基准文案。展示接口依次采用 NEXT_LOCALE Cookie、Accept-Language，没有支持的语言时回退英文。
- 错误中间件先记录原始英文异常及 OTel 状态，再翻译 HTTP 响应中的
error_msg。登录流程使用的smtp_invalid:和need_email_code:控制前缀保持不变。 - 任务类型、参数说明、执行记录和内置通知元数据使用请求内的副本进行翻译，避免修改共享注册表或持久化记录。
- 默认定时任务名称可翻译；管理员自定义名称、通知接收目标和已保存的消息模板保留原文。
- 新任务执行详情保存英文系统文案。历史中文文本通过已知的完整文案或格式模板在读取时展示为英文，不执行数据库回写。
格式模板只识别已登记的系统消息，并逐字保留捕获到的参数；时间戳也保留。未知消息原样返回。此兼容机制只用于系统拥有的展示字段，不能用来翻译任意用户数据，也不能通过比较翻译后的文本决定业务状态。任务重试和存储配置校验使用错误类型进行分类。
持久化兼容性
上传统计原有的六个中文分类名同时是数据库计数器键和 API 分类标识，不能当作标签直接改名。保留这些既有键，前端图表、图例和最大分类说明单独使用语言包标签；无需清空或重建现有统计。
历史 SQL 迁移、测试样例、中文项目文档以及用户已经保存的数据不属于待替换的运行时固定文案。离线页面和通知模板一旦由管理员选择、编辑并保存，就作为用户数据处理，不随界面语言切换而回写。
系统配置描述和内置邮件模板的名称、说明可能来自历史 seed。管理界面仅在配置键或内置模板键已登记、且文本与已知中英文默认值完全一致时，使用 builtin-metadata 语言分片展示；未知键、自定义描述与非内置模板保持原文。编辑表单保留原始状态，单纯保存其他字段不会把展示翻译写回数据库；邮件主题和正文始终按已保存内容显示。
校验与扩展
在仓库根目录运行 node scripts/audit-non-english.mjs 可生成完整的非 ASCII 文本清单，默认输出到被 Git 忽略的 .codex-artifacts/non-english-audit/。occurrences.csv 包含文件、行号、模块、分类和原文；JSON 另含字符位置、Unicode 码点、字符集及跳过的文件；review-candidates.csv 单列待审查源码。命令读取所有已跟踪和未被忽略的新文件，不按业务目录名称排除内容，也识别 Unicode 转义。
清单包含标点、表情、注释、文档、语言资源与历史迁移，不表示每个命中都需要替换。依赖、构建输出和私有环境文件不进入清单；二进制文件单独列出，不执行截图 OCR 或解包。生成的 Swagger 和中文文档站配置保留中文，既有上传分类键保留兼容性。字符集也不等同于语言，例如 Han 字符可能属于中文或日文。
pnpm check:i18n 校验中英文键一致性，并检查 Go、TypeScript/TSX 和安装脚本中的中文运行时文本；注释、语言资源、测试样例和上述六个持久化键有明确边界。该检查同时接入 make code-check 和现有前端 CI。
新增语言时，补齐前端分片、语言配置与 Provider 消息映射，以及服务端同名语言目录项，并验证格式占位符一致。新增系统消息仍以英文作为源文案，在相应语言资源中补齐译文。新增数据协议应使用稳定标识与参数，不再引入以中文显示文案充当持久化键的设计。