520

docs/spec/agreement_i18n_spec.md

@@ -0,0 +1,123 @@
+# 协议多语言适配 Spec
+
+创建时间: 2026-05-19
+更新时间: 2026-05-19
+状态: 开发中
+
+## 一、功能描述
+
+将闲言APP的10个协议/政策从纯中文扩展为**中文 + 英文**双语支持，同时网页端支持URL参数切换语言。
+
+## 二、支持语言
+
+| 优先级 | 语言 | 语言ID | 说明 |
+|--------|------|--------|------|
+| P0 | 简体中文 | zh_CN | 默认语言，已有 |
+| P0 | English | en | 国际通用语言，新增 |
+
+后续语言（P1+）：ja / zh_TW / es / ar / bn / hi / pt / ru / fr
+
+## 三、架构设计
+
+### 3.1 本地端（Flutter/Dart）
+
+#### 数据层 — `agreement_data.dart`
+
+- 每个协议新增英文常量：`_privacyPolicyEn` / `_userServiceAgreementEn` 等
+- `getContent(type, {languageId})` 增加语言参数，默认取当前语言
+- `getSubtitle(type, {languageId})` 同理
+- `getUpdateDate(type, {languageId})` 同理
+- 内部方法 `_currentLanguageId` 从Riverpod Provider获取当前语言
+
+#### 类型枚举 — `agreement_types.dart`
+
+- 枚举增加 `titleEn` 字段
+- 增加 `subtitleEn` 字段
+- 增加 `titleFor(String languageId)` 方法
+- 增加 `subtitleFor(String languageId)` 方法
+- `webUrl` 增加 `?lang=en` 参数支持
+
+#### 展示页面 — `agreement_page.dart`
+
+- 读取当前语言ID，传入 `getContent(type, languageId: langId)`
+- UI文案（"在线版"、"最后更新日期"等）走T翻译系统
+- 英文环境下"在线版"按钮跳转 `?lang=en` 版本
+
+#### 列表页面 — `agreement_list_page.dart`
+
+- 协议标题/副标题使用 `type.titleFor(langId)` / `AgreementData.getSubtitle(type, languageId: langId)`
+- 分组标题（"隐私与安全"等）走T翻译系统
+
+#### 翻译系统 — `translations.dart`
+
+TCommon/TSettings新增字段：
+- `agreements` / `agreementsAndPolicies` — 软件协议
+- `privacyAndSecurity` — 隐私与安全
+- `serviceTerms` — 服务条款
+- `contentAndCopyright` — 内容与版权
+- `aboutXianyan` — 了解闲言
+- `onlineVersion` — 在线版
+- `lastUpdated` — 最后更新日期
+- `readCarefully` — 请仔细阅读以下协议与政策
+
+### 3.2 网页端（HTML）
+
+#### URL语言参数
+
+```
+https://tools.wktyl.com/agreements/privacy-policy.html        → 默认中文
+https://tools.wktyl.com/agreements/privacy-policy.html?lang=en → 英文版
+```
+
+#### 生成脚本改造 — `generate_and_upload_agreements.py`
+
+- 从Dart文件提取中英文两套内容
+- 每个协议生成一个HTML文件，内含中英文两套 `<div class="lang-zh">` / `<div class="lang-en">`
+- JS根据URL参数 `?lang=en` 切换显示语言，默认显示中文
+- 页面顶部增加语言切换按钮（🌐 中文 / English）
+
+#### index.html改造
+
+- 增加语言切换按钮
+- 协议卡片标题/副标题双语
+- URL参数联动
+
+## 四、文件变更清单
+
+| 文件 | 变更类型 | 说明 |
+|------|----------|------|
+| `agreement_data.dart` | 修改 | 新增10个英文协议常量 + getContent增加语言参数 |
+| `agreement_types.dart` | 修改 | 枚举增加titleEn/subtitleEn + titleFor()方法 |
+| `agreement_page.dart` | 修改 | 读取当前语言，传入locale参数，UI文案走T翻译 |
+| `agreement_list_page.dart` | 修改 | 同上 |
+| `translations.dart` | 修改 | TCommon/TSettings增加协议相关翻译字段 |
+| `generate_and_upload_agreements.py` | 修改 | 提取英文内容，生成双语HTML + 语言切换JS |
+| `index.html` | 修改 | 增加语言切换功能 |
+
+## 五、实施阶段
+
+### Phase 1: Dart数据层
+- agreement_data.dart: 新增英文协议内容 + getContent语言参数
+- agreement_types.dart: 枚举多语言字段
+
+### Phase 2: 展示页面适配
+- agreement_page.dart: 多语言适配
+- agreement_list_page.dart: 多语言适配
+
+### Phase 3: 翻译系统
+- translations.dart: 协议相关UI文案翻译
+
+### Phase 4: 网页端
+- generate_and_upload_agreements.py: 双语HTML生成
+- index.html: 语言切换功能
+- 上传服务器验证
+
+## 六、验收标准
+
+1. 切换到英文后，协议内容显示英文版
+2. 切换到中文后，协议内容显示中文版
+3. 跟随系统语言自动选择协议语言
+4. 英文环境下"在线版"按钮跳转 `?lang=en` 版本
+5. 网页端 `?lang=en` 参数正常切换英文
+6. 网页端语言切换按钮正常工作
+7. 无英文翻译时fallback到中文