# 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` 的多语言能力已经从“页面零散替换”演进为“统一运行时 + 本地兜底 + 第三方适配”的可维护方案。

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