6f5400ec4b
- 重构「灵感」模块为「发现」模块，统一页面命名与文案 - 新增flutter_tts语音朗读依赖与鸿蒙Nearby配对方式 - 添加Android/iOS/鸿蒙全平台桌面小组件支持（7种类型） - 完善文件传输模块，新增画布邀请消息与删除会话功能 - 优化协作画布光标广播节流逻辑，修复已知bug - 更新应用英文名与隐私政策入口，新增翻译API抽象层 - 移除用户中心多余的加号按钮，完善空状态组件类型
200 lines
11 KiB
Dart
200 lines
11 KiB
Dart
/// ============================================================
|
||
/// 闲言APP — 多语言(i18n)升级开发文档 v2.0
|
||
/// 创建时间: 2026-05-19
|
||
/// 更新时间: 2026-05-19
|
||
/// 作用: 记录i18n系统问题诊断、升级方案、实施进度和归档验收
|
||
/// 上次更新: P0-P3全部完成，归档验收勾选
|
||
/// ============================================================
|
||
///
|
||
/// # 多语言(i18n)升级开发文档 v2.0
|
||
///
|
||
/// ## 一、问题诊断与优先级
|
||
///
|
||
/// | 优先级 | 问题 | 影响 | 状态 |
|
||
/// |--------|------|------|------|
|
||
/// | 🔴 P0 | 阿拉伯语RTL支持缺失 | 阿拉伯语完全不可用 | ✅ 已修复 |
|
||
/// | 🔴 P0 | 系统语言变化不监听 | "跟随系统"名不副实 | ✅ 已修复 |
|
||
/// | 🟡 P1 | T类130+参数不可维护 | 新增字段改动量巨大 | ✅ 已修复 |
|
||
/// | 🟡 P1 | 无参数化翻译/复数 | 动态内容无法翻译 | ✅ 已修复 |
|
||
/// | 🟡 P1 | 无翻译fallback机制 | 缺失翻译显示空白 | ✅ 已修复 |
|
||
/// | 🟢 P2 | 日期/数字格式化未联动 | 体验不完整 | ✅ 已修复 |
|
||
/// | 🟢 P2 | 翻译覆盖率无检测 | 协同翻译缺数据支撑 | ✅ 已修复 |
|
||
/// | 🟢 P2 | 协同翻译是空壳 | 无法协作翻译 | ✅ 已修复 |
|
||
/// | 🟢 P2 | localizationDelegates不完整 | Cupertino组件不跟随语言 | ✅ 已修复 |
|
||
/// | 🔵 P3 | 语言切换动画 | 体验优化 | ✅ 已修复 |
|
||
/// | 🔵 P3 | 更多语言支持(印地/葡/俄/法) | 市场扩展 | ✅ 已修复 |
|
||
///
|
||
/// ## 二、升级方案与实施
|
||
///
|
||
/// ### 2.1 ✅ P0: 阿拉伯语RTL支持
|
||
/// **方案**: AppLocale增加isRTL/textDirection属性，appLocaleProvider增加appTextDirectionProvider，
|
||
/// app.dart用Directionality包裹ScreenUtilInit
|
||
/// **文件**: app_locale.dart, app.dart
|
||
/// **实现**:
|
||
/// - `_rtlLanguageCodes = {'ar', 'he', 'fa', 'ur'}` 常量定义
|
||
/// - `AppLocale.isRTL` getter 判断当前语言是否RTL
|
||
/// - `AppLocale.textDirection` getter 返回 TextDirection.rtl/ltr
|
||
/// - `appTextDirectionProvider` Riverpod Provider，监听设置变化
|
||
/// - `app.dart` 外层 `Directionality(textDirection: textDirection, child: ScreenUtilInit(...))`
|
||
/// - 语言列表中阿拉伯语显示 RTL 标签
|
||
///
|
||
/// ### 2.2 ✅ P0: 系统语言变化监听
|
||
/// **方案**: _XianyanAppState增加didChangeLocales回调，
|
||
/// 通过SystemLocaleVersionNotifier触发Provider刷新
|
||
/// **文件**: app.dart, app_locale.dart
|
||
/// **实现**:
|
||
/// - `SystemLocaleVersionNotifier extends Notifier<int>` (Riverpod 3.0 不支持 StateProvider)
|
||
/// - `systemLocaleVersionProvider` NotifierProvider
|
||
/// - `appLocaleProvider` 和 `appTextDirectionProvider` 都 `ref.watch(systemLocaleVersionProvider)`
|
||
/// - `didChangeLocales` 回调调用 `ref.read(systemLocaleVersionProvider.notifier).increment()`
|
||
///
|
||
/// ### 2.3 ✅ P1: T类拆分分组
|
||
/// **方案**: T类改为组合模式，内含TNav/TSettings/TCommon/TProfile子类
|
||
/// 访问方式: t.nav.home / t.settings.language / t.common.cancel
|
||
/// **文件**: translations.dart
|
||
/// **实现**:
|
||
/// - TNav(3字段): home/discover/profile
|
||
/// - TCommon(16字段): cancel/ok/save/confirm/clear/reset/delete/success/failed/enabled/disabled/loading/view/search/entriesCountUnit/copyright
|
||
/// - TProfile(25字段): title/myFavorites/readingHistory/darkMode/...
|
||
/// - TSettings(100字段): language/generalSettings/interaction/sound/...
|
||
/// - T类保留144个@Deprecated getter向后兼容
|
||
/// - 7种语言常量全部更新为新构造函数
|
||
///
|
||
/// ### 2.4 ✅ P1: 参数化翻译
|
||
/// **方案**: 增加TFunc类，提供带参数的翻译方法
|
||
/// **文件**: translations.dart
|
||
/// **实现**:
|
||
/// - `TFunc` 类，构造函数接收 `_langId`
|
||
/// - `entriesCount(int count)` → "3 条" / "3 entries" / "3件"
|
||
/// - `greeting(String name)` → "你好，张三" / "Hello, 张三"
|
||
/// - `itemsSelected(int count)` → "已选3项" / "3 selected"
|
||
/// - `pluralItems(int count)` → 使用 Intl.plural 处理复数
|
||
/// - `translationsFuncProvider` Riverpod Provider
|
||
///
|
||
/// ### 2.5 ✅ P1: 翻译fallback
|
||
/// **方案**: T类增加T.withFallback静态方法
|
||
/// **文件**: translations.dart
|
||
/// **实现**:
|
||
/// - `T.withFallback(T target, T fallback)` — 将fallback中非空字段覆盖target空字段
|
||
/// - 新增语言时可先创建部分翻译，缺失字段自动回退到zh_CN
|
||
///
|
||
/// ### 2.6 ✅ P2: 日期/数字格式化
|
||
/// **方案**: 增加localeFormatProvider，基于当前locale提供DateFormat/NumberFormat
|
||
/// **文件**: app_locale.dart
|
||
/// **实现**:
|
||
/// - `localeDateFormatProvider` → `DateFormat.yMMMd(locale.toLanguageTag())`
|
||
/// - `localeNumberFormatProvider` → `NumberFormat.decimalPattern(locale.toLanguageTag())`
|
||
/// - 使用项目已有的 `intl: ^0.20.2` 依赖
|
||
///
|
||
/// ### 2.7 ✅ P2: 翻译覆盖率检测
|
||
/// **方案**: TranslationCoverage工具类 + 语言设置页面覆盖率面板
|
||
/// **文件**: translations.dart, language_settings_page.dart
|
||
/// **实现**:
|
||
/// - `TranslationCoverage.checkAll()` → `Map<String, int>` 各语言已翻译字段数
|
||
/// - `TranslationCoverage.checkCoverage(T target, T reference)` → 缺失字段列表
|
||
/// - `TranslationCoverage.totalFieldCount` → 总字段数
|
||
/// - 语言设置页底部显示覆盖率进度条（绿色100%/accent色<100%）
|
||
///
|
||
/// ### 2.8 ✅ P2: 协同翻译功能
|
||
/// **方案**: 导出翻译为JSON到剪贴板，CupertinoActionSheet操作面板
|
||
/// **文件**: translation_io_service.dart, language_settings_page.dart
|
||
/// **实现**:
|
||
/// - `TranslationIOService.exportToJson(T t)` → 当前语言JSON
|
||
/// - `TranslationIOService.exportAllToJson()` → 全部7种语言JSON
|
||
/// - `TranslationIOService.validateTranslationJson(String)` → 验证JSON格式
|
||
/// - 协同翻译按钮点击弹出ActionSheet: Export Current / Export All Languages
|
||
/// - 导出后自动复制到剪贴板 + 成功Toast
|
||
///
|
||
/// ### 2.9 ✅ P2: localizationDelegates补全
|
||
/// **方案**: 添加GlobalCupertinoLocalizations.delegate
|
||
/// **文件**: app.dart
|
||
/// **实现**:
|
||
/// - `_localizationsDelegates` 常量包含5个delegate
|
||
/// - GlobalMaterialLocalizations + GlobalWidgetsLocalizations + GlobalCupertinoLocalizations + DefaultCupertinoLocalizations + FlutterQuillLocalizations
|
||
/// - 鸿蒙端和非鸿蒙端统一使用
|
||
///
|
||
/// ## 三、归档验收清单
|
||
///
|
||
/// | # | 验收项 | 优先级 | 状态 |
|
||
/// |---|--------|--------|------|
|
||
/// | 1 | 阿拉伯语切换后界面RTL布局正确 | P0 | ✅ |
|
||
/// | 2 | 系统切换语言后APP自动跟随(无需重启) | P0 | ✅ |
|
||
/// | 3 | T类分组后所有现有翻译字段仍可访问 | P1 | ✅ |
|
||
/// | 4 | 参数化翻译(如"3条")正确显示各语言 | P1 | ✅ |
|
||
/// | 5 | 新增语言缺少翻译时fallback到中文 | P1 | ✅ |
|
||
/// | 6 | 日期格式随语言切换(中文→日语→英语) | P2 | ✅ |
|
||
/// | 7 | 调试面板可查看各语言翻译覆盖率 | P2 | ✅ |
|
||
/// | 8 | 协同翻译可导出JSON到剪贴板 | P2 | ✅ |
|
||
/// | 9 | Cupertino组件(如DatePicker)跟随语言 | P2 | ✅ |
|
||
/// | 10 | flutter analyze 零错误(仅info级lint) | P0 | ✅ |
|
||
///
|
||
/// ## 四、P3 实施记录
|
||
///
|
||
/// ### 4.1 ✅ P3: 语言切换动画
|
||
/// **方案**: _LocaleTransitionWrapper组件，监听locale变化触发淡入淡出
|
||
/// **文件**: app.dart
|
||
/// **实现**:
|
||
/// - `_LocaleTransitionWrapper extends StatefulWidget` + `SingleTickerProviderStateMixin`
|
||
/// - `AnimationController` 300ms duration
|
||
/// - `didUpdateWidget` 检测 `oldWidget.locale != widget.locale`
|
||
/// - `AnimatedBuilder` + `Opacity` 包裹子组件
|
||
/// - 尊重 `settings.animationEnabled` 开关
|
||
///
|
||
/// ### 4.2 ✅ P3: 更多语言支持
|
||
/// **方案**: AppLocale枚举增加4种语言 + translations.dart增加4种翻译常量
|
||
/// **文件**: app_locale.dart, translations.dart
|
||
/// **实现**:
|
||
/// - hi(印地语): हिन्दी, 天城文书写
|
||
/// - pt(葡萄牙语): Português, 拉丁字母
|
||
/// - ru(俄语): Русский, 西里尔字母
|
||
/// - fr(法语): Français, 拉丁字母
|
||
/// - 共11种语言 + 跟随系统
|
||
///
|
||
/// ### 4.3 ✅ P3: 翻译导入功能
|
||
/// **方案**: TranslationIOService.importFromJson() + CupertinoAlertDialog输入框
|
||
/// **文件**: translation_io_service.dart, language_settings_page.dart
|
||
/// **实现**:
|
||
/// - `importFromJson(String jsonStr, T fallback)` → 解析JSON+fallback缺失字段
|
||
/// - `_importNav/_importCommon/_importProfile/_importSettings` 私有方法
|
||
/// - 协同翻译ActionSheet增加"Import Translation"选项
|
||
/// - CupertinoTextField 6行输入框 + 验证 + 错误提示
|
||
///
|
||
/// ### 4.4 ✅ P3: 语言智能排序
|
||
/// **方案**: AppLocale.smartSorted()，根据系统语言计算相关性分数排序
|
||
/// **文件**: app_locale.dart, language_settings_page.dart
|
||
/// **实现**:
|
||
/// - `smartSorted()` 静态方法
|
||
/// - `_relevanceScore()` 计算分数: 匹配语言+国家100/匹配语言80/中文50/英文40/其他20
|
||
/// - 语言设置页使用 `AppLocale.smartSorted()` 替代 `AppLocale.selectable`
|
||
///
|
||
/// ## 五、归档验收清单（完整）
|
||
///
|
||
/// | # | 验收项 | 优先级 | 状态 |
|
||
/// |---|--------|--------|------|
|
||
/// | 1 | 阿拉伯语切换后界面RTL布局正确 | P0 | ✅ |
|
||
/// | 2 | 系统切换语言后APP自动跟随(无需重启) | P0 | ✅ |
|
||
/// | 3 | T类分组后所有现有翻译字段仍可访问 | P1 | ✅ |
|
||
/// | 4 | 参数化翻译(如"3条")正确显示各语言 | P1 | ✅ |
|
||
/// | 5 | 新增语言缺少翻译时fallback到中文 | P1 | ✅ |
|
||
/// | 6 | 日期格式随语言切换(中文→日语→英语) | P2 | ✅ |
|
||
/// | 7 | 调试面板可查看各语言翻译覆盖率 | P2 | ✅ |
|
||
/// | 8 | 协同翻译可导出JSON到剪贴板 | P2 | ✅ |
|
||
/// | 9 | Cupertino组件(如DatePicker)跟随语言 | P2 | ✅ |
|
||
/// | 10 | flutter analyze 零错误(仅info级lint) | P0 | ✅ |
|
||
/// | 11 | 语言切换时有淡入淡出过渡动画 | P3 | ✅ |
|
||
/// | 12 | 支持11种语言+跟随系统 | P3 | ✅ |
|
||
/// | 13 | 翻译导入功能可粘贴JSON导入 | P3 | ✅ |
|
||
/// | 14 | 语言列表按系统语言智能排序 | P3 | ✅ |
|
||
///
|
||
/// ## 六、文件变更追踪
|
||
///
|
||
/// | 文件 | 变更类型 | 说明 |
|
||
/// |------|----------|------|
|
||
/// | lib/l10n/app_locale.dart | 修改 | isRTL/textDirection/SystemLocaleVersionNotifier/appTextDirectionProvider/localeDateFormatProvider/localeNumberFormatProvider |
|
||
/// | lib/l10n/translations.dart | 重构 | TNav/TCommon/TProfile/TSettings子类+TFunc+TranslationCoverage+144个@Deprecated getter |
|
||
/// | lib/l10n/translation_io_service.dart | 新增 | 翻译导出/导入/验证服务 |
|
||
/// | lib/app/app.dart | 修改 | Directionality+didChangeLocales+GlobalCupertinoLocalizations+_localizationsDelegates常量 |
|
||
/// | lib/features/settings/presentation/language_settings_page.dart | 修改 | 协同翻译ActionSheet+覆盖率面板+RTL标识+t.nav/t.common/t.settings分组 |
|
||
/// | docs/i18n_dev_doc.dart | 修改 | 开发文档v2.0 |
|
||
/// | CHANGELOG.md | 修改 | v14.16.0版本记录 |
|