【开源鸿蒙跨平台开发训练营】Flutter框架鸿蒙应用的多语言环境适配实践
这次学习实践如何在鸿蒙App中通过Flutter框架实现多语言环境适配
欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
文章目录
- 功能实现 - 多语言（中文 / 英文）
- 一、期望目标
- 二、依赖与配置
- 2.1 依赖
- 2.2 l10n 配置
- 2.3 文案文件
- 三、实现说明
- 3.1 设置服务：语言持久化
- 3.2 应用入口：多语言与启动加载
- 3.3 设置页：语言入口与选择弹层
- 3.4 各页文案本地化
- 四、使用说明
- 五、涉及文件一览
- 六、开发与维护说明
- 结束语
如果项目需要支持多语言，在Flutter框架下鸿蒙如何实现呢？，往下看。
功能实现 - 多语言（中文 / 英文）
一、期望目标
- 目标：应用支持中文、英文两种语言，界面文案随语言切换；用户可在设置中选择语言或跟随系统，选择结果持久化并在下次启动生效。
- 方案：
- 使用 Flutter 官方 gen-l10n 方案：
flutter_localizations+ ARB 文案文件，通过flutter gen-l10n生成AppLocalizations。 - 在
main.dart中注册localizationsDelegates、supportedLocales，并用全局ValueNotifier（null 表示跟随系统）驱动MaterialApp.locale。 SettingsService持久化语言偏好（zh/en或未设置即跟随系统）；设置页增加「语言」入口，底部弹层选择「跟随系统 / 中文 / English」后更新 Notifier 并持久化，整应用即时切换语言。- 所有用户可见文案从各页面的硬编码中文改为
AppLocalizations.of(context)!.xxx，保证中英一致覆盖。
- 使用 Flutter 官方 gen-l10n 方案：
二、依赖与配置
2.1 依赖
文件：pubspec.yaml
- 新增：
flutter_localizations: sdk: flutter。 - 在
flutter:下增加generate: true，以启用 l10n 代码生成。
2.2 l10n 配置
文件：l10n.yaml（项目根目录）
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-class: AppLocalizations
2.3 文案文件
lib/l10n/app_en.arb：英文模板，包含全部 key 及占位符（如loadFailed的{error}、minutesAgo的{n}）。lib/l10n/app_zh.arb：中文翻译，key 与模板一致，@@locale": "zh"。
生成命令：在项目根目录执行 flutter gen-l10n，产物位于 .dart_tool/flutter_gen/gen_l10n/，通过 import 'package:flutter_gen/gen_l10n/app_localizations.dart'; 使用。
三、实现说明
3.1 设置服务：语言持久化
文件：lib/services/settings_service.dart
- 新增存储键：
_keyLocale = 'settings_locale'，取值：'zh'/'en'，未设置或空表示跟随系统。 - 新增方法：
Future：读取本地存储，默认返回null（跟随系统）。Future：写入或移除键以持久化。setLocale(Locale? locale)
3.2 应用入口：多语言与启动加载
文件：lib/main.dart
- 启动流程：在
runApp前除读取主题模式外，增加SettingsService().getLocale()得到初始语言，并创建appLocaleNotifier = ValueNotifier。 - MaterialApp：
- 在原有
ValueListenableBuilder内再包一层ValueListenableBuilder，将appLocaleNotifier.value赋给locale（null 时由 Flutter 使用系统语言）。 - 设置
localizationsDelegates：AppLocalizations.delegate、GlobalMaterialLocalizations.delegate、GlobalWidgetsLocalizations.delegate、GlobalCupertinoLocalizations.delegate。 - 设置
supportedLocales：Locale('en')、Locale('zh')。
- 在原有
3.3 设置页：语言入口与选择弹层
文件：lib/pages/profile_page.dart
- 在设置二级页 ListView 中增加 「语言」 入口（置于外观之上）：
- 标题：使用
l10n.language；副标题：当前语言文案（跟随系统 / 中文 / English），由_localeLabel(context)根据appLocaleNotifier.value计算。 - 点击后弹出底部弹层，三个
RadioListTile：跟随系统（themeSystem）、中文（languageChinese）、English（languageEnglish），groupValue为当前选中的'system'/'zh'/'en'。
- 标题：使用
- 选择后关闭弹层，将结果转为
Locale?（'system'→ null），更新appLocaleNotifier.value并调用SettingsService().setLocale(newLocale)，界面立即重建为所选语言。 - 设置页内其余文案（外观、隐私与安全、清除缓存、设置标题、缓存结果 SnackBar、退出登录对话框等）全部改为使用
AppLocalizations.of(context)!；主题模式弹层与_themeModeLabel改为接收AppLocalizations以输出中/英标签。
3.4 各页文案本地化
以下页面将硬编码中文替换为 AppLocalizations.of(context)! 或传入的 l10n，并在异步回调中注意 mounted 与 context 使用安全（先 if (!mounted) return; 再取 l10n）：
| 文件 | 修改要点 |
|---|---|
root_page.dart | 底部导航四个 Tab 的 label：首页/发现/消息/我的 → tabHome / tabSearch / tabMessages / tabProfile |
home_page.dart | 加载失败文案 loadFailed(e)、重试按钮 retry、暂无数据 noData；catch 内先 mounted 再取 l10n |
search_page.dart | 搜索 hint searchHint、重试 retry、暂无作品/未找到 noWorks / noMatchingWorks、加载失败 loadFailed(e) |
messages_page.dart | 消息标题、新建会话对话框（标题、hint、取消/添加）、会话名称校验与 SnackBar、点击进入聊天、暂无消息、时间格式 minutesAgo/hoursAgo/daysAgo； mock 会话名称与最后一条消息使用 l10n（设计小助手、系统通知、创作交流群等）；聊天详情输入框 hint、欢迎语 chatGreeting(name) |
profile_page.dart | 我的、示例用户 sampleUser、获赞/收藏、我的收藏/历史/设置/退出登录及副标题、历史记录页标题与暂无浏览记录、设置头标题、清除缓存结果、退出确认对话框全文 |
favorites_page.dart | 我的收藏标题、暂无收藏 noFavorites |
work_detail_page.dart | 暂无图片 noImages |
privacy_settings_page.dart | 隐私与安全标题、隐私政策/用户协议/账号与安全标题及正文（privacyPolicyContent / termsContent / accountSecurityContent） |
notification_settings_page.dart | 通知设置标题、接收通知/新消息通知/点赞与收藏通知的标题与副标题 |
upload_page.dart | 发布内容标题、标题/描述 label、校验文案、发布按钮、发布成功 SnackBar；异步中 mounted 后再 SnackBar |
四、使用说明
- 打开应用 → 底部「我的」→ 进入「设置」。
- 点击 「语言」（或 “Language”），在底部弹层中选择：
- 跟随系统：与系统语言一致（如系统为英文则应用为英文）；
- 中文：固定为简体中文；
- English：固定为英文。
- 选择后立即生效，且下次启动会保持上次选择。
五、涉及文件一览
| 文件 | 变更类型 |
|---|---|
pubspec.yaml | 新增 flutter_localizations、generate: true |
l10n.yaml | 新建，arb 目录与模板配置 |
lib/l10n/app_en.arb | 新建，英文模板 |
lib/l10n/app_zh.arb | 新建，中文翻译 |
lib/services/settings_service.dart | 新增 getLocale / setLocale、_keyLocale |
lib/main.dart | 启动加载 locale、appLocaleNotifier、localizationsDelegates、supportedLocales、locale |
lib/pages/root_page.dart | Tab 文案改为 l10n |
lib/pages/home_page.dart | 错误/重试/暂无数据 l10n，catch 内 mounted + l10n |
lib/pages/search_page.dart | 搜索 hint、重试、空状态、loadFailed l10n |
lib/pages/messages_page.dart | 消息/会话/聊天相关全部 l10n，mock 数据与时间格式 |
lib/pages/profile_page.dart | 语言入口与弹层、设置与个人页全部 l10n、主题弹层 l10n |
lib/pages/favorites_page.dart | 我的收藏、暂无收藏 l10n |
lib/pages/work_detail_page.dart | 暂无图片 l10n |
lib/pages/privacy_settings_page.dart | 标题与三段正文 l10n |
lib/pages/notification_settings_page.dart | 标题与三个开关标题/副标题 l10n |
lib/pages/upload_page.dart | 发布页全部 l10n，异步 SnackBar 前 mounted |
六、开发与维护说明
- 新增或修改文案：在
app_en.arb中增改 key（含占位符时需补@key的placeholders），在app_zh.arb中同步增改；随后执行flutter gen-l10n。 - 新增语言：在
lib/l10n/下新增app_，并在.arb main.dart的supportedLocales中增加对应Locale。 - 所有用户可见字符串应通过
AppLocalizations获取，避免在 UI 中硬编码中/英文。
结束语
感谢阅读本帖，如对贴中内容有意见和建议的，欢迎与我联系交流，也欢迎加入开源鸿蒙跨平台社区：
https://openharmonycrossplatform.csdn.net
