客户端多语言版本实施说明

一、总体结论

客户端要做多语言，建议从项目一开始就按“统一语言资源 + 各端本地化框架适配 + 后台可配置内容多语言化”的方式推进。

不要让 Android、iOS、Web、H5、鸿蒙、桌面端各自随便翻译一套文案。这样短期看起来快，后期会出现同一个按钮在不同端叫法不一致、翻译遗漏、版本无法同步、测试成本变高的问题。

建议采用的原则是：

1. 中文简体（zh-CN）作为第一版基准语言。
2. 所有客户端使用统一的文案 key。
3. 每个 key 在不同语言中维护对应翻译。
4. 客户端显示文字时不直接写死中文，而是读取多语言资源。
5. 用户可以跟随系统语言，也可以在 App 内手动切换语言。
6. 服务端、业务中台、管理后台下发的可配置内容，也要预留多语言字段。


二、第一批建议支持的语言

第一阶段不建议一次性做太多语言，否则翻译、测试和客服资料都会被拉长。

建议第一批支持：

1. 中文简体：zh-CN
2. 英文：en-US
3. 中文繁体：zh-TW

如果项目业务面向东南亚，可以在第二批加入：

4. 泰文：th-TH
5. 越南文：vi-VN
6. 印尼文：id-ID
7. 马来文：ms-MY

如果后续进入日韩市场，再加入：

8. 日文：ja-JP
9. 韩文：ko-KR

语言上线顺序应由业务市场决定，不建议纯技术侧一次性铺满。


三、统一语言资源怎么做

建议建立一个统一的语言 key 体系，例如：

app.name = 密联
auth.login.title = 密码登录
auth.login.phone = 手机号
auth.login.password = 密码
auth.login.submit = 登录
auth.register.title = 注册
auth.register.sendCode = 获取验证码
chat.conversation.empty = 暂无会话
chat.message.inputPlaceholder = 请输入消息
settings.language.title = 语言
settings.language.followSystem = 跟随系统

中文简体：

{
  "app.name": "密联",
  "auth.login.title": "密码登录",
  "auth.login.phone": "手机号",
  "auth.login.password": "密码",
  "auth.login.submit": "登录"
}

英文：

{
  "app.name": "MiLian",
  "auth.login.title": "Password Login",
  "auth.login.phone": "Phone Number",
  "auth.login.password": "Password",
  "auth.login.submit": "Log In"
}

繁体中文：

{
  "app.name": "密聯",
  "auth.login.title": "密碼登入",
  "auth.login.phone": "手機號",
  "auth.login.password": "密碼",
  "auth.login.submit": "登入"
}

重点不是格式一定要完全一样，而是所有端的 key 要统一。


四、各客户端推荐落地方式

1. Android APK / AAB

当前 Android 是 Flutter 技术路线。

建议使用 Flutter 官方国际化方案：

flutter_localizations
intl
ARB 语言文件
gen-l10n 自动生成多语言访问类

推荐文件结构：

android_flutter/lib/l10n/app_zh.arb
android_flutter/lib/l10n/app_en.arb
android_flutter/lib/l10n/app_zh_TW.arb

Flutter 页面中不要写死：

Text('登录')

而是改为：

Text(AppLocalizations.of(context).authLoginSubmit)

Android 端要支持：

系统语言自动识别
App 内手动切换语言
重启 App 后记住用户选择
未翻译文案回退到中文简体或英文


2. iOS IPA

如果 iOS 继续跟随 Flutter 工程，iOS 多语言也由同一套 Flutter ARB 文件生成，不需要 iOS 单独维护一套 Localizable.strings。

如果后续出现原生 iOS 页面，例如启动前权限页、推送说明、系统弹窗描述，则需要补：

ios/Runner/zh-Hans.lproj/InfoPlist.strings
ios/Runner/en.lproj/InfoPlist.strings
ios/Runner/zh-Hant.lproj/InfoPlist.strings

典型内容包括：

相机权限说明
相册权限说明
麦克风权限说明
通知权限说明
App 显示名称


3. 鸿蒙 HAP

鸿蒙如果采用 ArkTS / ArkUI，需要使用鸿蒙资源文件做本地化。

推荐结构方向：

entry/src/main/resources/base/element/string.json
entry/src/main/resources/zh_CN/element/string.json
entry/src/main/resources/en_US/element/string.json
entry/src/main/resources/zh_TW/element/string.json

ArkUI 页面中不要直接写死中文，要通过资源引用读取。

鸿蒙端同样要支持：

跟随系统语言
App 内手动切换语言
未翻译文案回退


4. Web 版

当前自研 Web 版是 Vue 3 单页应用。

建议使用：

vue-i18n

推荐结构：

web/src/locales/zh-CN.json
web/src/locales/en-US.json
web/src/locales/zh-TW.json

Vue 页面中不要写：

登录

而是使用：

{{ t('auth.login.submit') }}

Web 端要支持：

读取浏览器语言
用户手动切换语言
localStorage 保存选择
URL 或后台配置可指定默认语言
构建时检查缺失翻译


5. H5

H5 建议复用 Web 版 Vue 3 / vue-i18n 方案。

H5 额外要注意：

移动端按钮空间更小，英文、泰文、越南文可能更长，布局要留出弹性。
不要把按钮宽度写死。
表单错误提示要能自动换行。
弹窗标题、底部按钮、协议文案要做多语言。


6. PC / Mac / Linux 桌面端

如果桌面端采用 Electron 或 Tauri，并复用 Web 前端，则直接复用 Web 的 vue-i18n 语言包。

桌面端额外要处理：

菜单栏多语言
系统托盘菜单多语言
通知标题多语言
安装包名称和快捷方式名称
Windows / macOS / Linux 系统权限说明


7. iPadOS / Android Pad

平板端本质上跟随 iOS / Android 的多语言方案。

额外注意：

大屏布局中同一页面显示更多栏目，多语言后宽度变化更明显。
横屏双栏布局要测试英文和东南亚语言长度。
侧边栏、Tab、按钮不要固定过窄。


8. Watch / Car / Android TV / XR

这些后期终端不建议第一阶段投入完整多语言开发。

但第一阶段应该先把 key 体系定好，避免后期新增终端时重做文案。

这些终端更需要短文案：

Watch：极短通知、快捷回复
Car：语音播报、安全提示、免打扰
Android TV：遥控器可读的大字号文案
XR / AR / VR：空间提示、语音指令、浮层说明


五、后台和业务中台需要配合什么

客户端多语言不只是客户端自己的事。

业务中台后续要支持以下内容多语言：

1. App 名称
2. 启动页文案
3. 用户协议
4. 隐私政策
5. 公告
6. 运营弹窗
7. 帮助中心
8. 客服提示语
9. 敏感词提示
10. 审核拒绝原因
11. 会员套餐说明
12. 支付说明
13. 群公告模板
14. 系统通知模板

例如公告表不建议只存：

title
content

建议预留：

title_zh_cn
content_zh_cn
title_en_us
content_en_us
title_zh_tw
content_zh_tw

或者使用 JSON 结构：

title = {
  "zh-CN": "系统维护通知",
  "en-US": "System Maintenance Notice",
  "zh-TW": "系統維護通知"
}

content = {
  "zh-CN": "...",
  "en-US": "...",
  "zh-TW": "..."
}

如果业务内容没有对应语言，客户端应按规则回退：

用户选择语言
系统语言
英文
中文简体


六、哪些内容不应该翻译

有些内容不应该进入多语言翻译：

1. 用户昵称
2. 群名称
3. 用户自己输入的聊天内容
4. 文件名
5. 订单号
6. 手机号
7. 用户自定义备注
8. 自定义标签

这些内容属于用户数据，不应该自动翻译。

除非后续明确做“聊天消息自动翻译”功能，那是另一个独立功能，不等同于 App 多语言。


七、多语言和聊天消息自动翻译的区别

客户端多语言：

把 App 界面、按钮、菜单、错误提示、系统通知模板翻译成不同语言。

聊天消息自动翻译：

把用户 A 发给用户 B 的聊天内容翻译成另一种语言。

两者不是一回事。

第一阶段建议先做客户端多语言，不建议马上做聊天消息自动翻译。

聊天消息自动翻译需要额外考虑：

翻译接口成本
隐私合规
用户是否授权
原文和译文如何展示
群聊多语言场景
敏感词和误翻译风险


八、实施阶段建议

第一阶段：打基础

目标：

统一语言 key
Web 和 Android 先接入多语言框架
支持中文简体、英文、繁体中文
登录、注册、会话、联系人、设置页先完成多语言

建议先处理这些模块：

启动页
登录页
注册页
验证码
密码设置
会话列表
聊天输入框
联系人
我的/设置
错误提示


第二阶段：补全核心 IM

目标：

群组相关文案多语言
好友申请多语言
消息操作多语言
文件、图片、语音、视频消息类型提示多语言
系统通知模板多语言

建议处理：

新建群
加群
退群
解散群
群公告
群成员管理
消息撤回
消息转发
消息收藏
消息已读未读


第三阶段：业务中台多语言

目标：

后台可配置内容支持多语言。

建议处理：

公告
用户协议
隐私政策
帮助中心
运营弹窗
客服提示语
版本更新说明


第四阶段：更多客户端覆盖

目标：

iOS、鸿蒙、H5、桌面端、Pad 端同步使用同一套语言 key。

重点：

确保同一个功能在不同端的叫法一致。
确保同一个错误码在不同端展示一致。
确保同一个业务通知在不同端语言一致。


九、翻译管理建议

建议建立一个统一表格或翻译平台，字段至少包括：

key
中文简体
英文
中文繁体
使用场景
所属模块
最大长度建议
是否已确认
备注

示例：

key: auth.login.submit
中文简体: 登录
英文: Log In
中文繁体: 登入
模块: 登录
最大长度: 20
备注: 登录按钮

翻译不要只靠开发人员临时翻译。

重要业务文案建议由产品或业主确认。


十、测试验收标准

每个语言版本至少要测试：

1. App 首次打开能按系统语言显示。
2. App 内能手动切换语言。
3. 退出重进后语言选择仍然保留。
4. 登录、注册、验证码、密码错误等提示没有中文残留。
5. 会话列表、聊天页、联系人、设置页没有中文残留。
6. 文案过长时不遮挡、不重叠、不超出按钮。
7. 英文、繁体、东南亚语言在手机小屏也能正常显示。
8. 系统通知、推送标题、弹窗按钮语言正确。
9. 缺少翻译时有明确回退，不出现空白或 key 原文。
10. 同一功能在 Android、iOS、Web、H5 上叫法一致。


十一、当前项目建议马上做的事情

结合当前项目状态，建议按以下顺序推进：

1. 先给 Flutter Android 工程接入 Flutter 官方 l10n。
2. 把登录、注册、设置页中文文案抽成 key。
3. 同步建立中文简体、英文、繁体中文三套 ARB。
4. Web 端接入 vue-i18n。
5. Web 登录、注册、会话、联系人、设置页改成 key。
6. 在“我的 / 设置”中新增语言切换入口。
7. 将用户语言选择保存到本地。
8. 后续业务中台用户表预留 language 字段，记录用户偏好语言。
9. 管理后台后续增加公告、协议、帮助中心的多语言编辑能力。
10. 每次新增功能时，把多语言 key 作为开发完成标准之一。


十二、最终目标

最终目标不是简单把中文翻译成英文，而是让所有客户端形成同一套国际化能力：

同一个产品名称
同一套功能叫法
同一套错误提示
同一套系统通知模板
同一套语言切换逻辑
同一套回退规则

这样后续不管增加 iOS、鸿蒙、H5、桌面端、Pad、Watch、Car 还是海外市场，都不会因为多语言问题反复返工。