qiming/qiming-mobile/docs/i18n-progress-report.md

Qiming Mobile 多语言接入进度报告

1. 背景

本轮多语言改造的目标，不只是把部分页面文案替换成 t("...")，而是建立一套可以持续扩展的接入方案，覆盖以下几类场景：

• 业务页面与公共组件的用户可见文案
• 框架组件和原生 uni.* API 的提示文案
• 第三方库内部默认文案或运行时提示
• H5 语言切换后的动态刷新与兜底能力

当前项目已经完成一轮较完整的 i18n 基础建设与业务接入，核心主链路已可用，且具备继续扩展的基础。

2. 当前方案总览

2.1 核心运行时

项目以 utils/i18n.uts 作为统一多语言运行时，负责以下能力：

• 当前语言状态管理：i18nState.currentLang
• 词典缓存管理：本地缓存语言包与语言列表
• 文案查询：t(key)、translateText(text)
• 模板变量替换：支持 {name} 这类占位符
• 初始化加载：应用启动后加载远端语言包
• 语言切换：setLanguage(lang)
• 用户语言同步：syncLanguageFromUser(lang)
• H5 tabBar 文案同步：运行时调用 uni.setTabBarItem

这意味着项目内新增文案时，优先应接入这一层，而不是在页面里各自维护独立字典。

2.2 语言资源组织

当前语言资源由三层组成：

1. 远端词典 服务端通过 i18n 接口返回当前语言的词典映射，作为首选来源。

2. 本地默认语言文件 作为平台导入与本地兜底来源，主要文件为：

   • constants/i18n-locales/zh-CN.uts
   • constants/i18n-locales/zh-HK.uts
   • constants/i18n-locales/zh-TW.uts
   • constants/i18n-locales/en-US.uts

   当前项目已采用“标准语言码 + bundle 文件 key”双层方案：

   • 标准语言码：zh-CN、zh-TW、zh-HK、en-US
   • bundle 文件 key：zh-cn、zh-tw、zh-hk、en-us

   其中，运行时统一处理标准语言码归一，本地词包仍按小写文件 key 组织，避免将业务语言码与资源文件命名耦合在一起。

3. 本地字面量映射与兜底层 constants/i18n.local.constants.uts 负责：

   • 把历史遗留的中文字面量映射到 Mobile.* key
   • 在服务端未返回某个词条时，回退到本地默认语言
   • 在旧代码仍传原始中文时，尽量兼容显示

2.3 Key 规范

当前项目统一采用 Mobile.* 前缀管理业务文案，例如：

• Mobile.Nav.home
• Mobile.Auth.login
• Mobile.Chat.skill
• Mobile.ThirdParty.MpHtml.copyCode

这套命名已经覆盖导航、登录、聊天、文件预览、权限、第三方组件等主要模块。

2.4 框架组件与业务组件接入方式

当前推荐的接入方式分为两类：

1. 直接传 key 适用于明确是固定文案的标题、按钮、占位符，例如：

   • title="Mobile.Nav.agent"
   • placeholder="Mobile.AgentSearch.placeholder"

2. 组件内部统一走 translateText() 适用于公共组件既要兼容 i18n key，也要兼容旧调用方直接传中文或服务端返回文本的场景。

这样做的好处是：

• 新代码可以直接传 key
• 旧代码不必一次性全部重构
• 切语言时，动态文案仍可重新计算

2.5 第三方库接入方式

项目新增了 utils/i18n-third-party.uts 作为第三方语言适配层，当前职责包括：

• 维护第三方库当前语言状态
• 对外暴露统一同步入口 syncThirdPartyLocales(lang)
• 为第三方组件提供适配后的文案对象

目前已经落地的典型模式有：

1. 显式传入文案对象 例如给 uni-load-more 提供 content-text，避免继续使用组件内部默认语言逻辑。

2. 直接修改第三方组件内部用户可见文案 对一些不支持外部 locale 注入、但业务真实使用到的组件，直接将内部提示接到项目 i18n。

3. 避免循环依赖 第三方适配层不直接依赖运行时 t()，而是只依赖语言状态和本地兜底能力，降低循环引用风险。

3. 已完成能力

3.1 基础能力

当前已完成以下基础建设：

• i18n 运行时搭建完成
• 语言列表、语言词典、当前语言缓存机制完成
• H5 初始化语言加载接入完成
• H5 语言切换能力接入完成
• 用户登录后语言与后端用户配置同步完成
• H5 tabBar 文案运行时同步完成
• 本地默认语言文件拆分完成
• zh-TW / zh-HK 默认兜底语言文件已补齐
• i18n 标准语言码已统一为 zh-CN / zh-TW / zh-HK / en-US
• 本地字面量到 key 的兼容映射完成

3.2 业务主链路覆盖

当前主业务链路已完成较系统的文案接入，包括但不限于：

• 首页与 tab 页面
• 登录、验证码、重置密码链路
• 智能体列表与分类页
• 搜索页
• 临时会话页
• 聊天主链路
• 更多信息、相关会话、文件树、文件预览
• H5 webview 扩展页面
• 个人中心与语言切换页

H5 主链路中的标题、按钮、toast、modal、placeholder、loading、空态文案、部分 alt 文本都已经纳入统一管理。
微信小程序当前仍采用“固定简中”策略，因此小程序侧的静态中文配置属于当前设计范围，不视为本轮遗漏。

3.3 公共组件与基础组件覆盖

以下类型的组件已完成较多接入：

• 导航类组件：如 custom-nav-bar
• 列表/分页类组件：如 published-agent-list
• 下拉菜单/标签类组件：如 menu-dropdown
• 空态和图片描述类组件
• 聊天输入、录音、技能选择等高频组件

这些组件已逐步改成：

• 默认值使用 i18n key
• 渲染时通过 translateText() 兼容旧值与 key
• 避免只在初始化时计算一次文案，降低切语言后不刷新的风险

3.4 第三方库接入进度

当前已处理的第三方或框架相关模块包括：

• uni-load-more
• mp-html
• uni-ai-x
• uni-captcha
• x-tools
• lime-cascader 的业务实际调用路径

已完成的接入类型包括：

• 复制成功/失败提示
• 加载中/无更多/加载更多文案
• 弹窗标题、按钮、提示文案
• markdown 内部按钮与执行结果相关文案
• 验证码组件 placeholder、标题、错误提示
• 文件或系统工具提示文案

4. 当前进度判断

从当前仓库状态看，可以把进度分为三个层次：

4.1 已经完成

• H5 主业务用户可见文案的多语言主链路基本打通
• H5 多语言切换、初始化加载、用户语言同步已具备
• 多数高频公共组件已收口到统一方案
• 多个真实使用中的第三方库已完成接入

4.2 基本完成但仍需维护

• 历史兼容路径仍存在部分“中文字面量 -> key”的桥接逻辑
• 某些组件仍需依赖 translateText() 兼容旧调用方式
• 第三方库新增升级后，仍需按既有方案继续补接

4.3 尚未完全收敛的部分

当前仓库里仍可能存在以下残留，但优先级较低：

• 注释中的中文
• 调试日志中的中文
• unpackage 构建产物中的旧文案
• 第三方库 demo / example 页面中的演示文案
• 未被当前业务真正引用的三方组件内部默认文案

另外，pages.json 等配置层仍保留部分静态中文默认值。
在当前“小程序固定简中、H5 运行时覆盖”的策略下，这些配置属于平台级默认值，而不是本轮多语言漏接项。

这些内容不会直接阻塞当前业务多语言能力，但会影响后续全仓扫描时的噪音与维护成本。

另外，从语言资源建设角度看，当前已经完成繁中默认资源补齐，但后续仍需要继续关注：

• zh-TW 与 zh-HK 是否需要进一步按地区表达细化词条
• 后端语言列表与前端标准语言码是否完全一致

这类工作属于语言资源层和接口协同层的持续优化，不会改变当前主链路方案，但会影响后续多地区文案的一致性。

5. 已知边界与风险

5.1 H5 与小程序行为不同

当前策略中：

• H5 支持动态语言切换
• 微信小程序仍保持固定简中策略，当前不提供动态切换能力

因此如果后续要扩展小程序语言切换，需要重新评估：

• 平台能力限制
• 页面初始化时机
• tabBar 与页面标题刷新策略

5.2 第三方库不一定支持标准 locale 注入

不是所有第三方库都提供官方多语言入口，当前项目实际采用了三种手段：

• 外部传入文案
• 包装适配
• 直接修改第三方源码

这意味着第三方升级时，需要特别关注：

• 改动是否被覆盖
• API 是否变化
• 已接入的 i18n patch 是否失效

5.3 历史兼容逻辑仍然存在

为降低一次性迁移成本，当前保留了对旧文案传入方式的兼容。这带来两个结果：

• 优点：旧代码不必一次性全部重构
• 风险：新同学可能继续误传中文字面量，而不是直接传 key

因此后续应逐步推动“新增代码默认传 key”成为团队共识。

6. 推荐接入规范

后续新增页面、组件或三方库时，建议统一遵循以下规范。

6.1 新增业务文案

• 优先新增 Mobile.* key
• 同步补齐 zh-CN.uts、zh-HK.uts、zh-TW.uts 与 en-US.uts
• 若涉及历史兼容，再视情况补 i18n.local.constants.uts

6.2 公共组件

• 组件 props 默认值尽量写 key，不直接写中文
• 渲染时统一走 translateText()
• 对只允许固定 key 的新组件，可在文档中明确约束，逐步减少兼容负担

6.3 用户提示类 API

以下场景必须优先检查是否已接 i18n：

• uni.showToast
• uni.showModal
• uni.showLoading
• uni.setNavigationBarTitle
• 输入框 placeholder
• 图片 alt

6.4 第三方库

新增第三方库接入时，优先按以下顺序评估：

1. 是否支持官方 locale 配置
2. 是否可以通过 props 外部注入文案
3. 是否需要在 utils/i18n-third-party.uts 增加适配入口
4. 是否必须 patch 第三方源码

7. 后续建议

基于当前进度，后续建议按以下顺序推进：

1. 补充这份报告对应的维护约定 包括“新增文案必须补双语 key”“新增第三方需评估 locale 入口”等约束。

2. 持续校验标准语言码与 bundle key 的映射关系 重点确保 zh-CN / zh-TW / zh-HK / en-US 与本地词包 key、后端接口返回值、缓存值保持一致。

3. 持续做低优先级清理 将业务源码中的中文日志、历史 fallback、非核心残留继续收敛，降低全仓扫描噪音。

4. 继续完善第三方审计 对真实业务已使用但尚未完全收口的第三方组件，做按需补接。

5. 结合现有审计能力持续验证 当前已有执行记录文档与多轮扫描结果，后续建议将报告、规则与审计结果保持同步。

8. 结论

截至当前版本，qiming-mobile 的多语言能力已经从“页面零散替换”演进为“统一运行时 + 本地兜底 + 第三方适配”的可维护方案。

从业务价值上看，当前主链路已经具备实际可用的多语言支撑能力；从工程角度看，也已经形成了继续扩展所需的基础结构。剩余工作主要集中在低优先级清理、第三方长尾收口，以及后续团队协作过程中的规范执行。