312 lines
11 KiB
Markdown
312 lines
11 KiB
Markdown
# 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` 的多语言能力已经从“页面零散替换”演进为“统一运行时 + 本地兜底 + 第三方适配”的可维护方案。
|
||
|
||
从业务价值上看，当前主链路已经具备实际可用的多语言支撑能力；从工程角度看，也已经形成了继续扩展所需的基础结构。剩余工作主要集中在低优先级清理、第三方长尾收口，以及后续团队协作过程中的规范执行。
|