deveco_hmigbot 0.21.5

package/skills/migrate-core/references/topics/env-doctor.md

@@ -0,0 +1,245 @@
+<!-- 原技能 hmos-env-doctor，已吸收为 migrate-core 语料专题，不再单独注册 -->
+> HarmonyOS 开发环境检测与修复。在迁移、编译、运行 HarmonyOS 项目前自动诊断环境问题。当用户说"编译失败"、"环境有问题"、"hvigorw 找不到"、"签名错误"、"真机运行白屏"、"网络请求失败"、"检查一下环境"、"为什么编译不过"时触发。也适用于项目初始化后的环境健康检查、DevEco Studio CLI 编译配置、以及迁移前的环境预检。即使用户只说"帮我看看哪里有问题"或者"跑不起来"，也应触发。
+
+# HarmonyOS 环境医生
+
+## 1. 定位
+
+开发环境诊断工具。在 HarmonyOS 项目迁移或开发过程中，自动检测 DevEco Studio、SDK、编译工具链、签名配置、权限声明、网络环境等问题，输出诊断报告并提供一键修复方案。
+
+**解决的核心痛点**：HarmonyOS 开发涉及多个工具链（hvigorw、ohpm、Java、Node.js、SDK），任何一个缺失或配置错误都会导致编译失败或运行异常，而错误信息往往不直观。本 skill 将散落的环境知识整合为系统化的检查清单。
+
+---
+
+## 2. 触发时机
+
+- 项目初始化后，首次尝试编译前
+- 编译失败且错误信息指向环境问题
+- 真机/模拟器运行出现白屏、闪退、网络失败
+- Android→HarmonyOS 迁移开始前的环境预检
+- 用户主动请求环境检查
+
+---
+
+## 3. 诊断清单（按优先级排序）
+
+### 3.1 DevEco Studio 定位
+
+DevEco Studio 是 HarmonyOS 开发的核心 IDE，内置了编译、打包、签名所需的全部工具。
+
+**检测步骤**：
+```bash
+# 常见安装路径（按优先级搜索）
+for drive in C D E F; do
+  find "/$drive/" -maxdepth 4 -name "DevEco*" -type d 2>/dev/null
+done
+```
+
+**需要从 DevEco Studio 中提取的工具**：
+| 工具 | 相对路径 | 用途 |
+|------|---------|------|
+| hvigorw | tools/hvigor/bin/hvigorw | 项目编译 |
+| ohpm | tools/ohpm/bin/ohpm | 包管理 |
+| java | jbr/bin/java | Java 运行时（打包需要） |
+| node | tools/node/bin/node | Node.js 运行时 |
+| SDK | sdk/default/openharmony/ | HarmonyOS SDK |
+
+**环境变量设置模板**：
+```bash
+export DEVECO_HOME="/path/to/DevEco Studio"
+export PATH="$DEVECO_HOME/tools/hvigor/bin:$DEVECO_HOME/tools/ohpm/bin:$DEVECO_HOME/jbr/bin:$PATH"
+export DEVECO_SDK_HOME="$DEVECO_HOME/sdk"
+export JAVA_HOME="$DEVECO_HOME/jbr"
+```
+
+**诊断结果**：
+- PASS: DevEco Studio 找到，工具链完整
+- FAIL: 未找到 → 提示安装 DevEco Studio
+- WARN: 找到但版本过旧 → 提示升级
+
+### 3.2 编译工具链验证
+
+定位到 DevEco Studio 后，验证各工具是否可用：
+
+```bash
+hvigorw --version    # 期望: 6.x.x
+ohpm --version       # 期望: 有输出
+java --version       # 期望: JDK 17+
+node --version       # 期望: v18+
+```
+
+**常见故障**：
+| 错误信息 | 原因 | 修复 |
+|---------|------|------|
+| `hvigorw: command not found` | PATH 未设置 | 添加 DevEco tools/hvigor/bin 到 PATH |
+| `spawn java ENOENT` | Java 不在 PATH | 添加 DevEco jbr/bin 到 PATH |
+| `Cannot find module 'xxx'` | node_modules 缺失 | 运行 `ohpm install` |
+| `The SDK license agreement is not accepted` | 新机/流水线 SDK 组件从未接受许可（实测一批 20 应用里 3 个整轮报废于此） | 迁移前先空跑一次 `hvigorw assembleHap --no-daemon`；报此错即按错误文本指引：DevEco Studio SDK Manager 重下对应版本 Toolchains/ArkTS/JS/Native/Previewer 并接受许可，或命令行 SDK 工具重下时接受许可；接受后再开工，不在迁移中途处理 |
+
+### 3.3 签名配置检查
+
+签名问题是 HarmonyOS 编译中最常见的环境卡点。
+
+**检测步骤**：
+1. 读取 `build-profile.json5` 中的 `signingConfigs`
+2. 检查 `storeFile`、`certpath`、`profile` 路径是否在本机存在
+3. 如果路径指向其他用户目录（如 `/Users/xxx/`）→ 签名配置来自其他机器
+
+**修复策略（按优先级）**：
+1. **方案 A**: 在 DevEco Studio 中重新配置自动签名（File → Project Structure → Signing Configs）
+2. **方案 B**: 移除 `signingConfig` 引用，生成 unsigned HAP（开发调试用）
+   ```json5
+   // build-profile.json5 中移除这一行:
+   // "signingConfig": "default",
+   ```
+3. **方案 C**: 手动创建签名文件（生产发布用）
+
+**判断逻辑**：
+- 路径存在 + 文件有效 → PASS
+- 路径不存在但为本机路径 → FAIL: 签名文件缺失
+- 路径指向其他用户/机器 → FAIL: 签名配置来自其他环境
+- 无 signingConfigs 字段 → WARN: 将生成 unsigned HAP
+
+### 3.4 Python 环境（可选工具）
+
+部分迁移脚本（synthesize_view_xml.py 等）需要 Python。
+
+```bash
+python3 --version || python --version
+```
+
+**缺失时的影响和降级策略**：
+- 影响: 无法运行确定性脚本合成 view.xml，页面 confidence 降为 medium
+- 降级: LLM 直接分析源码生成 meta.json（精度略低但可用）
+- 建议: 安装 Python 3.8+ 可提升 UI 还原精度
+
+### 3.5 项目配置检查
+
+**module.json5 权限声明**：
+```bash
+grep -q "ohos.permission.INTERNET" entry/src/main/module.json5
+```
+
+缺少 INTERNET 权限是真机上网络请求静默失败的最常见原因。
+
+**必须声明的权限**（网络类应用）：
+```json5
+"requestPermissions": [
+  { "name": "ohos.permission.INTERNET" },
+  { "name": "ohos.permission.GET_NETWORK_INFO" }
+]
+```
+
+**app.json5 身份检查**：
+- `bundleName` 不应为 `com.example.*`（模板默认值）
+- `vendor` 不应为 `example`
+- 检查 `versionName` 是否已从 Android 同步
+
+**main_pages.json 入口检查**：
+- 检查 `src` 数组第一项是否指向实际的启动页（不是默认的 `pages/Index`）
+- 检查 EntryAbility.ets 中 `loadContent` 路径与 main_pages.json 首项一致
+
+### 3.6 真机/模拟器运行时问题
+
+当应用编译通过但运行异常时，检查以下项：
+
+**白屏/内容为空**：
+- 原因 1: `aboutToAppear` 中 async 调用失败，状态变量（`@Local` V2 / `@State` V1）保持初始空值
+  - 检查: grep "aboutToAppear" 中的 async 调用，是否有同步 fallback
+  - 修复: 关键展示数据同步初始化，async 作为增强
+- 原因 2: ForEach 未提供 key generator，class 实例 key 冲突
+  - 检查: grep "ForEach" 是否有第三个参数（key generator）
+  - 修复: 添加 `(item) => item.uniqueId` 作为 key generator
+- 原因 3: 网络权限缺失，API 请求静默失败
+  - 检查: module.json5 是否有 INTERNET 权限
+
+**闪退**：
+- 原因 1: crypto API 在某些设备上不可用
+  - 检查: 是否使用了 cryptoFramework 且未 try-catch
+  - 修复: crypto 调用必须有 try-catch + fallback
+- 原因 2: 未注册的页面路由
+  - 检查: main_pages.json 是否包含所有页面
+  - 修复: 确保每个 @Entry 页面都在 src 数组中
+
+**网络请求失败**：
+- 原因 1: 缺少 INTERNET 权限
+- 原因 2: HTTP 明文传输被阻止（需配置 network_security_config）
+- 原因 3: API 域名不可达（检查 DNS/代理）
+
+### 3.7 子代理权限（宿主相关）
+
+并行子代理可能无法访问 Android 源码目录（多数宿主默认只授权工作目录）。
+
+**检测**：子代理是否能读取 `$ANDROID_SRC` 路径下的文件。
+
+**修复**：
+- 方案 A: 按宿主权限机制放行该目录（DevEco Code：推荐工作目录同时包含 Android 源码与鸿蒙工程，权限询问时允许）
+- 方案 B: 将 Android 源码复制到工作目录下
+- 方案 C: 主会话 fallback（效率低但可用）
+
+---
+
+## 4. 诊断报告格式
+
+```markdown
+# 环境诊断报告
+
+| 检查项 | 状态 | 详情 |
+|--------|------|------|
+| DevEco Studio | PASS/FAIL | 路径: xxx, 版本: xxx |
+| hvigorw | PASS/FAIL | 版本: xxx |
+| Java | PASS/FAIL | 版本: xxx |
+| Node.js | PASS/FAIL | 版本: xxx |
+| Python | PASS/WARN | 版本: xxx (可选) |
+| 签名配置 | PASS/FAIL/WARN | 状态描述 |
+| 网络权限 | PASS/FAIL | module.json5 |
+| App 身份 | PASS/WARN | bundleName/vendor |
+| 入口页面 | PASS/FAIL | main_pages.json + EntryAbility |
+
+## 需要修复的项
+1. ...
+2. ...
+
+## 修复命令
+(自动生成的修复脚本)
+```
+
+---
+
+## 5. 自动修复能力
+
+对于可安全自动修复的问题，skill 直接执行修复：
+
+| 问题 | 自动修复 | 操作 |
+|------|---------|------|
+| PATH 未设置 | YES | 输出 export 命令 |
+| 缺少 INTERNET 权限 | YES | 追加到 module.json5 |
+| 签名指向其他机器 | YES | 移除 signingConfig 引用 |
+| main_pages.json 入口错误 | YES | 更新 src 数组 |
+| bundleName 为模板默认值 | ASK | 提示用户输入正确的包名 |
+| Python 缺失 | NO | 提示安装命令 |
+| DevEco Studio 缺失 | NO | 提示下载链接 |
+
+---
+
+## 6. 使用示例
+
+```
+检查一下环境
+```
+→ 运行完整诊断清单，输出报告
+
+```
+编译失败了，spawn java ENOENT
+```
+→ 定位 Java 问题，输出 PATH 修复命令
+
+```
+真机上模版列表是空的
+```
+→ 检查网络权限 + async fallback + ForEach key
+
+```
+开始迁移前先检查一下
+```
+→ 运行预检清单（DevEco + 签名 + Python + 权限）

package/skills/migrate-core/references/topics/i18n/README.md

@@ -0,0 +1,458 @@
+> ⚠ 本文样例中 `getContext(this)` 为已废弃写法：组件内一律改 `this.getUIContext().getHostContext()`；Ability 内用 `this.context`。
+
+<!-- 原技能 arkts-i18n，已吸收为 migrate-core 语料专题，不再单独注册 -->
+> ArkTS/HarmonyOS 国际化（i18n）技能（V2 优先，API 12+）。当用户需要添加多语言支持、实现动态语言切换、配置资源文件、处理国际化资源目录结构、扫描硬编码字符串，或任何与"国际化"、"多语言"、"切换语言"相关的问题时，务必触发此 skill。 即使用户只是说"怎么添加英文"或"怎么做中英文切换"，也应触发。
+
+
+# ArkTS I18N — 国际化指南（V2 优先）
+
+## API 版本与项目策略
+
+本 skill 的代码示例基于 **API 12+（HarmonyOS 5.0.0+）和 ArkTS V2 装饰器体系**。
+
+> **项目锁 V2**：所有新生成的"语言切换 / locale 状态 / refreshKey"代码使用 V2 装饰器（`@ComponentV2 / @Local / @Param / @Once / @ObservedV2 / @Trace / AppStorageV2.connect / PersistenceV2.globalConnect`）。i18n 相关 API（`resourceManager` / `intl` / `$r('app.string.xxx')` / `i18n.System.setAppPreferredLanguage` / `getAppPreferredLanguage` / `onConfigurationUpdate`）在 V1/V2 之间**完全不变**。
+>
+
+V1 → V2 关键差异（仅与本 skill 相关的 state 部分）：
+
+| V1 | V2 |
+|---|---|
+| `@Component` | `@ComponentV2` |
+| `@State refreshKey: number = 0` | `@Local refreshKey: number = 0` |
+| `@StorageLink('currentLanguage') lang: string = 'zh'` | `@Local locale: LocaleModel = AppStorageV2.connect(LocaleModel, 'locale', () => new LocaleModel())!`（需先定义 `@ObservedV2 LocaleModel`） |
+| `@Prop currentColumns: number = 3` | `@Param @Once currentColumns: number = 3`（只读） |
+| `@Watch('lang') onLangChange()` | `@Monitor('lang') onLangChange(m: IMonitor)` |
+| `AppStorage.setOrCreate('refreshKey', n)` | `localeModel.refreshKey = n`（直接改 @Trace 字段，自动同步） |
+| `PersistentStorage.persistProp('currentLanguage', 'zh')` | `PersistenceV2.globalConnect({ type: LocaleModel, key: 'locale', defaultCreator: () => new LocaleModel() })` |
+
+> **重要**：i18n 业务 API（`i18n.System.setAppPreferredLanguage()` / `$r()` / `onConfigurationUpdate()` 等）**与装饰器版本无关**。本次升级仅替换状态装饰器，API 调用方式不变。
+
+---
+
+## 触发场景
+
+- "怎么做国际化"、"添加多语言支持"
+- "实现中英文切换"
+- "资源文件怎么组织"
+- "动态切换语言不生效"
+- "怎么添加日语/韩语/其他语言"
+- "扫描硬编码字符串"、"找出没有国际化的文本"
+- 迁移流程内批量翻译待办时按下方"自动翻译模式"手动触发（历史自动集成已随旧管线移除）
+
+---
+
+## 自动翻译模式（批量翻译待办的标准流程）
+
+当 `spec/placeholder-registry.md` 含 `kind=resource-pending-translation` 条目时，按以下步骤执行：
+
+```
+skill({
+  skill: "arkts-i18n",
+  args: "task=translate-pending-todos source_locale=base target_locales=<auto-detect> registry=spec/placeholder-registry.md"
+})
+```
+
+收到 `task=translate-pending-todos` 时，按以下流程执行（不需要用户介入）：
+
+### 自动流程
+
+1. **读 registry** — 解析 `spec/placeholder-registry.md`，过滤 `kind=resource-pending-translation` 且 `status ∈ {registered, pending}` 的所有条目；每条 `location` 字段形如 `entry/src/main/resources/<locale>/element/<file>.json:<key>`
+2. **按 locale 分组** — 每个目标 locale 单独处理
+3. **逐 key 翻译** — 对每个 P-ID，读出 `[TODO: translate]` 前缀的英文原值，按目标 locale 生成真实翻译（LLM 按本 skill 既有"步骤 4：添加到 string.json"风格产出）。术语一致性参考 `references/code-examples.md` / `references/language-codes.md`
+4. **落盘** — 用 Edit/Write 把真实翻译写回对应 `resources/<locale>/element/<file>.json` 的 `value` 字段，**移除 `[TODO: translate]` 前缀**
+5. **跨 locale 一致性验证** — 跑 `scripts/audit_i18n_completeness.sh --project-root <abs> --output-json docs/i18n-audit.json`；若 FAIL 则报告 missing keys 并停止
+6. **更新 registry** — 把已处理的 P-ID 的 `status` 字段从 `registered` / `pending` 改为 `resolved`
+7. **返回报告** — 输出 `{translated_count, locales, audit_pass, updated_registry_path}` 结构化结果
+
+### 异常处理
+
+- 任一 locale 的翻译产出无法通过审阅（含未翻译英文、术语不一致等）→ 保留 `[TODO: translate]` 前缀 + registry status 不更新 + `failed_translations[]` 写进迁移报告
+- `audit_i18n_completeness.sh` 退出码 1（key_missing）→ 同上
+
+> 此模式下 LLM 充当翻译引擎，但**仍可被独立审阅**——产出的翻译会留在 git working tree，用户跑完整 pipeline 后随时可 review / amend。
+
+---
+
+## 核心概念
+
+HarmonyOS 国际化基于「**资源文件目录分级**」和「**系统语言检测**」：
+
+```
+resources/
+├── base/           // Fallback 资源（无匹配时使用）
+├── zh_CN/          // 简体中文
+├── en_US/          // 美国英文
+└── ja/             // 日文
+```
+
+- **静态引用**：`$r('app.string.xxx')` 由系统根据当前语言自动加载
+- **动态切换**：通过 `i18n.System.setAppPreferredLanguage()` 手动指定语言
+
+### ⚠️ base/ 目录的作用
+
+**base/ 不是"中文目录"，而是 Fallback 目录！**
+
+```
+资源匹配规则：
+1. 系统根据当前语言查找匹配目录（zh-CN → zh_CN、zh-Hans、zh）
+2. 找到匹配目录？→ ✅ 使用该目录的资源
+3. 未找到？→ 使用 base/ 目录的资源（Fallback）
+```
+
+---
+
+## 资源文件结构
+
+### 标准目录结构
+
+```
+src/main/resources/
+├── base/                      # Fallback 资源
+│   ├── element/
+│   │   └── string.json        # 字符串资源
+│   └── media/                  # 图片资源
+├── zh_CN/                     # 简体中文
+│   └── element/
+│       └── string.json
+├── en_US/                     # 美国英文
+│   ├── element/
+│   │   └── string.json
+│   └── media/
+│       └── logo.png           # 英文版 logo（可选）
+└── ja/                        # 日文
+    └── element/
+        └── string.json
+```
+
+### 目录命名规范
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 语言 | ISO 639-1 | `en`, `ja`, `ko`, `zh` |
+| 语言+区域 | ISO 639-1 + ISO 3166-1 | `zh_CN`, `en_US`, `zh_TW` |
+
+> ⚠️ 目录名必须完全匹配，否则系统无法识别
+
+---
+
+## 字符串资源文件
+
+### JSON 格式
+
+**base/element/string.json**：
+```json
+{
+  "string": [
+    { "name": "app_name", "value": "App Name" },
+    { "name": "confirm", "value": "Confirm" }
+  ]
+}
+```
+
+**zh_CN/element/string.json**：
+```json
+{
+  "string": [
+    { "name": "app_name", "value": "应用名称" },
+    { "name": "confirm", "value": "确认" }
+  ]
+}
+```
+
+### 引用方式
+
+```typescript
+// 静态引用
+Text($r('app.string.app_name'))
+Button($r('app.string.confirm'))
+Image($r('app.media.logo'))
+```
+
+### 插值参数（占位符）
+
+```json
+// string.json
+{ "name": "file_count", "value": "共 %d 个文件" }
+```
+
+```typescript
+// 代码中替换
+const str = resourceManager.getStringByNameSync('file_count')
+const message = str.replace('%d', count.toString())
+```
+
+---
+
+## 语言范围由资源目录决定
+
+module.json5 **没有** `supportedLanguages` 字段（hvigor 模块 schema 无此项，写了校验报错）。应用支持哪些语言 = `resources/` 下有哪些 locale 目录（`base/` 必有；`zh_CN/`、`en_US/`、`zh_HK/`、`ja_JP/` … 按平台限定符命名）；`i18n.System.setAppPreferredLanguage(lang)` 设到没有资源目录的语言时，`$r` 回退 `base/`。
+
+---
+
+## 动态语言切换（V2）
+
+### 基本实现
+
+V2 项目用 `@Local` 持有 refreshKey；i18n API 不变：
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+import { common } from '@kit.AbilityKit'
+
+@Entry
+@ComponentV2
+struct LanguageSettings {
+  private context = getContext(this) as common.UIAbilityContext
+  @Local private refreshKey: number = 0
+
+  async switchLanguage(lang: string): Promise<void> {
+    i18n.System.setAppPreferredLanguage(lang)   // 同步；之后加载的资源按此语言取，已渲染页面靠 refreshKey 重建
+    this.refreshKey++  // 触发 UI 重建
+  }
+
+  build() {
+    Column() {
+      Text($r('app.string.welcome'))
+        .fontSize(20)
+    }
+    .id('lang_' + this.refreshKey)
+  }
+}
+```
+
+### 全局共享 locale 状态（V2 推荐）
+
+把 `currentLanguage` / `refreshKey` 封装到一个 `@ObservedV2 LocaleModel`，用 `AppStorageV2.connect` 在所有页面共享单例：
+
+```typescript
+// common/LocaleModel.ets
+@ObservedV2
+export class LocaleModel {
+  @Trace currentLanguage: string = 'zh'
+  @Trace refreshKey: number = 0
+}
+
+// 任意 V2 组件
+@ComponentV2
+struct AnyPage {
+  @Local locale: LocaleModel = AppStorageV2.connect(
+    LocaleModel,
+    'locale',
+    () => new LocaleModel()
+  )!
+
+  build() {
+    Column() {
+      Text($r('app.string.hello'))
+        .id('page_' + this.locale.refreshKey)  // refreshKey 改 → 自动重建
+    }
+  }
+}
+```
+
+> 修改 `this.locale.refreshKey++` 即可同步刷新所有 `connect` 同一 key 的组件，无需 V1 `@StorageLink` 散字段。
+
+### 获取当前系统语言
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+
+getCurrentLanguage(): string {
+  return i18n.System.getAppPreferredLanguage() || 'zh'   // 同步返回应用当前生效语言（如 'zh-Hans'）；resourceManager 没有 getPreferredLanguage
+}
+```
+
+### 监听语言变化
+
+```typescript
+// 在 EntryAbility 中（UIAbility 只有 onConfigurationUpdate 一个配置变化回调，没有单独的语言回调）
+onConfigurationUpdate(config: Configuration): void {
+  if (config.language !== undefined) hilog.info(0x0000, 'I18N', `Language changed: ${config.language}`)
+}
+```
+
+---
+
+## 图片国际化
+
+```
+resources/
+├── base/media/logo.png         # 默认 logo
+├── en/media/logo.png           # 英文版 logo（同名）
+└── zh_CN/media/logo.png        # 中文版 logo（同名）
+```
+
+```typescript
+// 同一引用路径，不同语言加载不同文件
+Image($r('app.media.logo'))
+```
+
+> ⚠️ 不同语言目录下的图片**文件名必须一致**
+
+---
+
+## 常见错误
+
+### 错误 1：硬编码字符串
+
+```typescript
+// ❌ 错误
+Text('确认')
+Button('登录')
+
+// ✅ 正确
+Text($r('app.string.confirm'))
+Button($r('app.string.login'))
+```
+
+### 错误 2：目录命名错误
+
+```typescript
+// ❌ 错误
+resources/chinese/element/string.json
+
+// ✅ 正确
+resources/zh_CN/element/string.json
+```
+
+### 错误 3：语言没有对应资源目录
+
+`setAppPreferredLanguage` 设到没有 `resources/<locale>/` 的语言，`$r` 回退 `base/`，表现像"不生效"——补对应 locale 目录（module.json5 没有 supportedLanguages 字段）。
+
+### 错误 4：动态切换后 UI 不更新
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+// ❌ 错误 — 直接返回
+i18n.System.setAppPreferredLanguage(lang)
+
+// ✅ 正确 — 触发重建
+i18n.System.setAppPreferredLanguage(lang)
+this.refreshKey++
+```
+
+### 错误 5：string.json 格式错误
+
+```json
+// ❌ 错误 — value 被双引号包裹
+{ "name": "app_name", "value": "\"图库\"" }
+
+// ✅ 正确
+{ "name": "app_name", "value": "图库" }
+```
+
+---
+
+## 硬编码字符串扫描与迁移
+
+当用户需要**扫描项目中的硬编码字符串并迁移到 resources**时，执行以下流程：
+
+### 步骤 1：扫描硬编码
+
+```bash
+rg "Text\(['\"]" --type ets -n
+rg "Button\(['\"]" --type ets -n
+rg "showToast\(['\"]" --type ets -n
+```
+
+### 步骤 2：识别需要迁移的字符串
+
+**排除**：已使用 `$r()` 引用、URL、代码变量、正则、单字符
+
+**需要迁移**：
+```typescript
+Text('确认')
+Button('取消')
+.title('设置页面')
+promptAction.showToast('操作成功')
+```
+
+### 步骤 3：生成资源 key
+
+| 场景 | key 格式 | 示例 |
+|------|---------|------|
+| 按钮 | `btn_xxx` | `btn_confirm`, `btn_cancel` |
+| 标题 | `title_xxx` | `title_settings` |
+| 消息 | `msg_xxx` | `msg_delete_confirm` |
+| Toast | `toast_xxx` | `toast_save_success` |
+
+### 步骤 4：添加到 string.json
+
+**base/element/string.json**：
+```json
+{ "name": "confirm", "value": "确认" }
+```
+
+**en_US/element/string.json**：
+```json
+{ "name": "confirm", "value": "Confirm" }
+```
+
+### 步骤 5：替换代码
+
+```typescript
+// 替换前
+Text('确认')
+
+// 替换后
+Text($r('app.string.confirm'))
+```
+
+### 步骤 6：验证
+
+**1) 跨 locale key 一致性** — 规则：`string.json` / `plural.json` / `strarray.json` 里 base 的全部 `name` 必须在每个
+**language locale**（zh_CN / en_US / ...）出现；**mode locale**（dark / horizontal / vertical 等）按差异覆盖即可，豁免。
+对比办法：取 base 与各语言目录同名文件的 `name` 集合求差集（`node -e` 或 `jq` 一行即可，无需专用脚本），差集非空 = 缺翻译，
+补齐后再编译。
+
+> 资源 value 内未注册的 `[TODO: translate]` / 裸 TODO 占位由集成闭合 check-stubs 统一扫描，两者职责正交。
+
+**2) 手工 / 编译检查**：
+
+- [ ] 所有用户可见字符串都已替换为 `$r()` 引用
+- [ ] 替换后能正常编译
+
+---
+
+## 生成检查清单
+
+- [ ] 资源目录使用标准语言代码
+- [ ] string.json 格式正确
+- [ ] 所有用户可见字符串使用 `$r()` 引用
+- [ ] 需要的语言都有 `resources/<locale>/` 目录（module.json5 没有 supportedLanguages 字段）
+- [ ] 不同语言目录下的图片文件名一致
+- [ ] 已扫描硬编码字符串并迁移到 resources
+
+---
+
+## API 验证状态
+
+| API | 状态 |
+|-----|------|
+| `resourceManager.getStringByNameSync()` | ✅ 已验证 |
+| `resourceManager.getStringByName()` | ✅ SDK 有声明（异步，返回 Promise<string>） |
+| `i18n.System.setAppPreferredLanguage()` | ✅ SDK 有声明（应用级语言设置） |
+| `i18n.System.getAppPreferredLanguage()` | ✅ SDK 有声明（同步返回 string）；`resourceManager.getPreferredLanguage` 不存在 |
+| `$r('app.string.xxx')` | ✅ 已验证 |
+
+---
+
+## References
+
+详细文档和完整代码示例请参阅（**全部代码示例已升级 V2**）：
+
+| 文件 | 内容 |
+|------|------|
+| `references/dynamic-language-switch.md` | 动态语言切换完整代码（V2，含 LocaleModel） |
+| `references/common-pitfalls.md` | 避坑指南与错误对照表（V2） |
+| `references/language-codes.md` | 语言代码对照表（ISO 标准） |
+| `references/code-examples.md` | ColumnsDialog 等代码示例（V2） |
+
+---
+
+## 相关专题
+
+| 需要什么 | 读取哪里 |
+|---------|---------|
+| V2 状态管理（@Local / @Param / @Event / AppStorageV2）与跨页传 locale | 工单 conventions §A2 状态条目为准；不确定的装饰器语义 grep 本机 SDK `.d.ts` |
+