@harmonyos-arkts/d2h 0.0.0-stage → 0.1.1

package/skills/arkts-i18n/references/code-examples.md

@@ -0,0 +1,302 @@
+# 代码仓验证示例（V2）
+
+> 基于代码仓实际实现的完整代码示例。**本项目锁 V2**：所有 struct 用 `@ComponentV2`，状态用 `@Local / @Param / @ObservedV2`。i18n API（`resourceManager.getStringByNameSync` / `$r()` 等）与装饰器版本无关。
+>
+> V1 老项目兼容写法见 [`v1-compat.md`](./v1-compat.md)。
+
+---
+
+## ✅ 已验证：获取字符串资源
+
+基于 `entry/src/main/ets/components/dialogs/ColumnsDialog.ets:9-22`
+
+```typescript
+import { common } from '@kit.AbilityKit'
+import { hilog } from '@kit.PerformanceAnalysisKit'
+
+const DOMAIN = 0xFF00
+const TAG = 'ColumnsDialog'
+
+@CustomDialog
+export struct ColumnsDialog {
+  dialogController: CustomDialogController
+
+  aboutToAppear(): void {
+    try {
+      const context = getContext(this) as common.UIAbilityContext
+      const resourceManager = context.resourceManager
+      
+      // ✅ 已验证：同步获取字符串资源
+      const str = resourceManager.getStringByNameSync('dialog_column')
+      hilog.info(DOMAIN, TAG, `Loaded string: ${str}`)
+    } catch (err) {
+      const error = err as Error
+      hilog.error(DOMAIN, TAG, `Failed to load string: ${error.message}`)
+    }
+  }
+}
+```
+
+**关键点**：
+1. ✅ 使用 `getContext(this)` 获取 context
+2. ✅ 使用 `resourceManager.getStringByNameSync()` 同步获取字符串
+3. ✅ 使用 try-catch 处理错误
+
+---
+
+## ✅ 已验证：语言环境检测
+
+> 基于代码仓 `components/dialogs/ColumnsDialog.ets:7-16` 的实际实现
+
+**适用场景**：
+- 需要根据语言执行不同逻辑（如复数处理）
+- 不依赖未知 API 的可靠方案
+- 判断当前加载的是中文还是英文资源
+
+**完整实现**：
+
+```typescript
+@ComponentV2
+export struct ColumnsDialog {
+  /**
+   * 检测当前语言环境是否为中文
+   * @returns true 表示中文环境，false 表示非中文环境
+   */
+  private isChineseLocale(): boolean {
+    const context = getContext(this)
+    const resourceManager = context.resourceManager
+    try {
+      // 获取任意包含中文的字符串
+      const str = resourceManager.getStringByNameSync('dialog_column')
+      // 检测中文字符（Unicode 范围：0x4e00 - 0x9fa5）
+      return /[\u4e00-\u9fa5]/.test(str)
+    } catch {
+      return false  // 默认非中文环境
+    }
+  }
+}
+```
+
+**原理解释**：
+- `[\u4e00-\u9fa5]` 匹配中文常用汉字的 Unicode 范围
+- 如果字符串包含中文字符，说明加载了中文资源
+- 无需依赖未知 API，可靠性高
+
+**使用示例**：
+
+```typescript
+if (this.isChineseLocale()) {
+  // 中文环境：无需复数处理
+  label = `${count} 列`
+} else {
+  // 英文环境：需要复数处理
+  label = count === 1 ? '1 column' : `${count} columns`
+}
+```
+
+**注意事项**：
+- ✅ 选择有明显中文特征的字符串（如 'dialog_column'、'app_name'）
+- ✅ 提供 try-catch 错误处理
+- ✅ 提供默认返回值（false）
+- ⚠️ 字符串需要包含中文才能准确判断
+
+---
+
+## ✅ 已验证：复数处理完整实现
+
+> 基于代码仓 `components/dialogs/ColumnsDialog.ets:18-31` 的实际实现
+
+**适用场景**：
+- 需要显示带数字的文本（如 "3 列"、"3 columns"）
+- 英文环境需要复数处理
+- 需要动态替换占位符
+
+**完整代码示例**：
+
+```typescript
+@ComponentV2
+export struct ColumnsDialog {
+  @Param @Once currentColumns: number = 3
+
+  /**
+   * 获取列数标签（带复数处理）
+   * @param num 列数
+   * @returns 格式化后的字符串
+   */
+  private getColumnLabel(num: number): string {
+    const context = getContext(this)
+    const resourceManager = context.resourceManager
+    
+    try {
+      // 1. 获取字符串资源（包含占位符 %d）
+      let str = resourceManager.getStringByNameSync('dialog_column')
+      // str = "%d 列" (中文) 或 "%d column" (英文)
+      
+      // 2. 替换占位符
+      str = str.replace('%d', num.toString())
+      
+      // 3. 英文复数处理（大于1时添加 's'）
+      if (num > 1 && !this.isChineseLocale() && !str.endsWith('s')) {
+        str = str + 's'  // "2 column" → "2 columns"
+      }
+      
+      return str
+    } catch {
+      // 4. 兜底逻辑：确保始终有返回值
+      return num === 1 ? '1 column' : `${num} columns`
+    }
+  }
+}
+```
+
+**处理流程**：
+1. **获取字符串资源**：从 string.json 加载（含占位符 `%d`）
+2. **替换占位符**：`str.replace('%d', value)` 替换为实际数字
+3. **判断复数**：`num > 1 && !isChineseLocale() && !str.endsWith('s')`
+4. **添加复数标记**：英文环境且 num > 1 时添加 's'
+5. **兜底逻辑**：确保异常时也有返回值
+
+**关键点**：
+- ✅ 占位符替换：`str.replace('%d', value.toString())`
+- ✅ 复数判断：`num > 1 && !isChineseLocale() && !str.endsWith('s')`
+- ✅ 兜底逻辑：`catch { return num === 1 ? '1 column' : `${num} columns` }`
+
+**支持的占位符**：
+
+| 占位符 | 类型 | 示例 string.json | 替换结果 |
+|--------|------|-----------------|----------|
+| `%d` | 整数 | `"%d 列"` | `"3 列"` |
+| `%s` | 字符串 | `"文件：%s"` | `"文件：photo.jpg"` |
+| `%f` | 浮点数 | `"大小：%f MB"` | `"大小：1.5 MB"` |
+
+**注意事项**：
+- ⚠️ 仅支持规则复数（+s），不规则复数需特殊处理（如 child → children）
+- ⚠️ 中文字符串无需复数处理
+- ✅ 始终提供兜底逻辑，避免崩溃
+- ✅ 使用 `toString()` 转换数字为字符串
+
+---
+
+## ✅ 已验证：完整业务场景示例（ColumnsDialog）
+
+> 基于代码仓 `components/dialogs/ColumnsDialog.ets` 的完整实现
+
+**业务场景**：让用户选择网格列数（1-20），需要：
+- 显示格式化文本（"3 列" 或 "3 columns"）
+- 根据语言环境处理复数
+- 提供友好的用户界面
+
+**完整代码**：
+
+```typescript
+@ComponentV2
+export struct ColumnsDialog {
+  @Param @Once currentColumns: number = 3
+  @Event onColumnsChange: (columns: number) => void = () => {}
+  @Event onCancel: () => void = () => {}
+
+  // ✅ 技术点1：语言环境检测
+  private isChineseLocale(): boolean {
+    const context = getContext(this)
+    const resourceManager = context.resourceManager
+    try {
+      const str = resourceManager.getStringByNameSync('dialog_column')
+      return /[\u4e00-\u9fa5]/.test(str)
+    } catch {
+      return false
+    }
+  }
+
+  // ✅ 技术点2：复数处理 + 占位符替换
+  private getColumnLabel(num: number): string {
+    const context = getContext(this)
+    const resourceManager = context.resourceManager
+    try {
+      let str = resourceManager.getStringByNameSync('dialog_column')
+      str = str.replace('%d', num.toString())
+      
+      // 英文复数处理
+      if (num > 1 && !this.isChineseLocale() && !str.endsWith('s')) {
+        str = str + 's'
+      }
+      return str
+    } catch {
+      // 兜底逻辑
+      return num === 1 ? '1 column' : `${num} columns`
+    }
+  }
+
+  @Builder
+  columnOption(num: number) {
+    Row() {
+      Text(this.currentColumns === num ? '✓ ' : '  ')
+        .fontSize(14)
+        .fontColor('#007DFF')
+        .width(24)
+      Text(this.getColumnLabel(num))
+        .fontSize(14)
+        .fontColor(this.currentColumns === num ? '#007DFF' : '#333333')
+    }
+    .width('100%')
+    .padding({ left: 12, right: 12, top: 10, bottom: 10 })
+    .backgroundColor(this.currentColumns === num ? '#E6F0FF' : '#FFFFFF')
+    .borderRadius(8)
+    .margin({ bottom: 4 })
+    .onClick(() => {
+      this.onColumnsChange(num)
+    })
+  }
+
+  build() {
+    Column() {
+      // ✅ 技术点3：静态资源引用
+      Text($r('app.string.dialog_columns_title'))
+        .fontSize(18)
+        .fontWeight(FontWeight.Bold)
+        .margin({ top: 20, bottom: 16 })
+
+      Scroll() {
+        Column() {
+          // 动态生成 1-20 的列选项
+          ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20], 
+            (num: number) => {
+              this.columnOption(num)
+            }
+          )
+        }
+        .width('100%')
+      }
+      .constraintSize({ maxHeight: 360 })
+      .scrollBar(BarState.Auto)
+
+      Button($r('app.string.dialog_cancel'))
+        .width('100%')
+        .height(40)
+        .backgroundColor('#F0F0F0')
+        .fontColor('#333333')
+        .margin({ top: 16 })
+        .onClick(() => this.onCancel())
+    }
+    .width(280)
+    .padding(20)
+    .backgroundColor('#FFFFFF')
+    .borderRadius(16)
+  }
+}
+```
+
+**技术要点总结**：
+
+| 技术点 | 代码位置 | 说明 |
+|--------|---------|------|
+| 语言环境检测 | `isChineseLocale():7-16` | 通过中文字符判断语言 |
+| 复数处理 | `getColumnLabel():18-31` | 占位符替换 + 复数规则 |
+| 占位符替换 | `getColumnLabel():23` | `str.replace('%d', value)` |
+| 静态引用 | `build():56` | `$r('app.string.xxx')` |
+| 动态获取 | `getColumnLabel():22` | `resourceManager.getStringByNameSync()` |
+| 错误处理 | `getColumnLabel():28-30` | try-catch + 兜底逻辑 |
+
+**文件位置**：
+- 实现代码：`entry/src/main/ets/components/dialogs/ColumnsDialog.ets`
+- 中文资源：`entry/src/main/resources/base/element/string.json`
+- 英文资源：`entry/src/main/resources/en_US/element/string.json`

package/skills/arkts-i18n/references/common-pitfalls.md

@@ -0,0 +1,391 @@
+# 国际化避坑指南（V2）
+
+> 常见国际化错误与正确做法对照表。**本项目锁 V2**：所有代码示例使用 `@ComponentV2 / @Local / @ObservedV2 / @Trace / AppStorageV2`。i18n API（`resourceManager` / `$r()` 等）与装饰器版本无关。
+>
+> V1 老项目兼容写法见 [`v1-compat.md`](./v1-compat.md)。
+
+---
+
+## ⚠️ 文档说明
+
+- ✅ **已验证项**：基于代码仓实际使用或官方文档
+- ⚠️ **未验证项**：需要查证官方文档确认
+- 💡 **建议**：使用前查阅 https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/i18n-overview-V5
+
+---
+
+## 目录命名错误
+
+### 错误 vs 正确
+
+| 错误写法 | 正确写法 | 说明 |
+|---------|---------|------|
+| `chinese` | `zh` | 使用 ISO 639-1 |
+| `china` | `zh_CN` | 使用 ISO 639-1 + ISO 3166-1 |
+| `Chinese` | `zh-Hans` | 小写，或带区域码 |
+| `zh-CN` | `zh_CN` | 下划线而非连字符（部分版本接受连字符） |
+| `en-uk` | `en_GB` | 英国英文用 `en_GB` |
+
+### 完整语言代码参考
+
+| 语言 | 代码 | 区域变体 |
+|------|------|---------|
+| 中文 | `zh` | `zh_CN`, `zh_HK`, `zh_TW`, `zh_Hans`, `zh_Hant` |
+| 英文 | `en` | `en_US`, `en_GB`, `en_AU`, `en_CA` |
+| 日文 | `ja` | - |
+| 韩文 | `ko` | - |
+| 德文 | `de` | `de_DE`, `de_AT`, `de_CH` |
+| 法文 | `fr` | `fr_FR`, `fr_CA`, `fr_CH` |
+| 西班牙文 | `es` | `es_ES`, `es_MX`, `es_AR` |
+| 葡萄牙文 | `pt` | `pt_BR`, `pt_PT` |
+| 俄文 | `ru` | - |
+| 阿拉伯文 | `ar` | - |
+
+---
+
+## string.json 格式错误
+
+### 错误 1：value 使用错误引号
+
+```json
+// 错误 — value 被双引号包裹
+{
+  "string": [
+    { "name": "app_name", "value": "\"图库\"" }
+  ]
+}
+
+// 正确 — value 直接是字符串
+{
+  "string": [
+    { "name": "app_name", "value": "图库" }
+  ]
+}
+```
+
+### 错误 2：缺少必要字段
+
+```json
+// 错误 — 缺少 name 或 value
+{
+  "string": [
+    { "value": "图库" },
+    { "name": "app_name" }
+  ]
+}
+
+// 正确
+{
+  "string": [
+    { "name": "app_name", "value": "图库" }
+  ]
+}
+```
+
+### 错误 3：JSON 语法错误
+
+```json
+// 错误 — 尾随逗号
+{
+  "string": [
+    { "name": "a", "value": "A" },
+    { "name": "b", "value": "B" },  // ← 尾随逗号
+  ]
+}
+
+// 正确
+{
+  "string": [
+    { "name": "a", "value": "A" },
+    { "name": "b", "value": "B" }
+  ]
+}
+```
+
+---
+
+## 硬编码字符串
+
+### 错误 vs 正确
+
+| 错误写法 | 正确写法 |
+|---------|---------|
+| `Text('确认')` | `Text($r('app.string.confirm'))` |
+| `Button('取消')` | `Button($r('app.string.cancel'))` |
+| `'共 ' + count + ' 个文件'` | `$r('app.string.file_count', count)` |
+| `promptAction.showToast('操作成功')` | `promptAction.showToast($r('app.string.success'))` |
+
+### 容易硬编码的地方
+
+1. **Button 文字**
+2. **Dialog 标题和内容**
+3. **Toast 消息**
+4. **Placeholder 文案**
+5. **Error 消息**
+6. **Menu 项**
+7. **Tab 标签**
+
+---
+
+## 动态切换不生效
+
+### 原因 1：未声明 supportedLanguages
+
+```json5
+// module.json5
+{
+  "module": {
+    "supportedLanguages": ["zh", "en", "ja"]  // ← 必须声明
+  }
+}
+```
+
+### 原因 2：UI 未触发重建
+
+```typescript
+// 错误 — 切换后 UI 不更新
+async switchLanguage(lang: string) {
+  await resMgr.setPreferredLanguage([lang])
+  // 直接返回，UI 不会更新
+}
+
+// 正确 — 触发状态更新
+async switchLanguage(lang: string) {
+  await resMgr.setPreferredLanguage([lang])
+  this.refreshKey++  // 触发重建
+  this.currentLang = lang
+}
+```
+
+### 原因 3：组件未持有响应式 locale 状态
+
+```typescript
+// 错误 — 组件不响应状态变化
+@Entry
+@ComponentV2
+struct Page {
+  build() {
+    Column() {
+      Text($r('app.string.hello'))  // 不会自动更新
+    }
+  }
+}
+
+// 正确 — 使用 @Local + LocaleModel 包装
+@ObservedV2
+class LocaleModel {
+  @Trace currentLanguage: string = 'zh'
+  @Trace refreshKey: number = 0
+}
+
+@Entry
+@ComponentV2
+struct Page {
+  @Local locale: LocaleModel = AppStorageV2.connect(
+    LocaleModel, 'locale', () => new LocaleModel()
+  )!
+
+  build() {
+    Column() {
+      Text($r('app.string.hello'))
+        .id('page_' + this.locale.refreshKey)  // refreshKey 改即重建
+    }
+  }
+}
+```
+
+> V2 关键点：`@Local` 持有 `@ObservedV2` 实例 → 实例的 `@Trace` 字段变化自动刷新该组件。无需 V1 的 `@StorageLink('refreshKey')` 单字段绑定。
+
+---
+
+## 图片国际化问题
+
+### 错误：文件名不一致
+
+```
+base/media/
+└── logo.png      ✓
+
+en/media/
+└── logo_en.png  ✗ 应该是 logo.png
+
+ja/media/
+└── logo_jp.png  ✗ 应该是 logo.png
+```
+
+### 正确做法
+
+```
+base/media/
+└── logo.png      ✓
+
+en/media/
+└── logo.png      ✓（同名文件，内容不同）
+
+ja/media/
+└── logo.png      ✓（同名文件，内容不同）
+```
+
+---
+
+## 插值参数使用错误
+
+> ⚠️ **验证状态**：`IntlString.format()` API 需要查证官方文档
+> 
+> **推荐方案**：使用字符串模板 ` \`...${variable}...\` ` 或 `resourceManager.getStringByName()`
+
+### 错误 1：参数顺序错误
+
+```typescript
+// string.json: { "name": "info", "value": "文件：%s，大小：%s" }
+
+// ⚠️ 以下 API 需要查证 - IntlString.format 可能不存在
+// 错误 — 参数顺序颠倒
+// IntlString.format($r('app.string.info'), size, name)
+
+// ✅ 推荐 — 使用字符串模板
+const name = 'photo.jpg'
+const size = '1.5MB'
+const message = `文件：${name}，大小：${size}`
+
+// ⚠️ 或者 — 如果 resourceManager 支持参数
+// resourceManager.getStringByName('info', name, size)
+```
+
+### 错误 2：参数类型不匹配
+
+```typescript
+// string.json: { "name": "count", "value": "数量：%d" }
+
+// ⚠️ 以下 API 需要查证
+// 错误 — 传字符串
+// IntlString.format($r('app.string.count'), '10')
+
+// ✅ 推荐 — 使用字符串模板
+const count = 10
+const message = `数量：${count}`
+```
+
+### 错误 3：参数数量不匹配
+
+```typescript
+// string.json: { "name": "info", "value": "%s 大小：%s" }
+
+// ⚠️ 以下 API 需要查证
+// 错误 — 只传一个参数
+// IntlString.format($r('app.string.info'), name)
+
+// ✅ 推荐 — 使用字符串模板
+const name = 'file.txt'
+const size = '2KB'
+const message = `${name} 大小：${size}`
+```
+
+---
+
+## RTL 语言注意事项
+
+阿拉伯文、希伯来文等 RTL（从右到左）语言需要额外处理：
+
+### 1. 布局适配
+
+```typescript
+// 检测 RTL
+import { i18n } from '@kit.LocalizationKit'
+
+const isRTL = i18n.isRTL()
+```
+
+### 2. 布局方向
+
+```typescript
+Column() {
+  // RTL 语言下自动反转
+}
+.layoutDirection(isRTL ? LayoutDirection.RTL : LayoutDirection.LTR)
+```
+
+### 3. 图片翻转
+
+```typescript
+Image($r('app.media.arrow'))
+  .rotate({ angle: isRTL ? 180 : 0 })  // 箭头方向需反转
+```
+
+---
+
+## module.json5 supportedLanguages 陷阱
+
+### 问题：声明了但不生效
+
+```json5
+// module.json5
+{
+  "module": {
+    "supportedLanguages": ["zh", "en"]
+  }
+}
+```
+
+可能原因：
+1. **语言代码不匹配**：`"zh-Hans"` vs `"zh"`
+2. **应用未重启**：切换语言后需要重启应用
+3. **资源文件缺失**：声明了但对应目录不存在
+
+### 正确声明
+
+```json5
+{
+  "module": {
+    "supportedLanguages": [
+      "zh",        // 中文（默认）
+      "zh-Hans",   // 简体中文（API 12+）
+      "zh-Hant",   // 繁体中文（API 12+）
+      "en",        // 英文
+      "ja"         // 日文
+    ]
+  }
+}
+```
+
+---
+
+## 调试技巧
+
+### 1. 打印当前语言
+
+```typescript
+import { resourceManager } from '@kit.LocalizationKit'
+
+const langs = await context.resourceManager.getPreferredLanguage()
+hilog.info(0x0000, 'I18N', 'Current language: %{public}s', langs[0])
+```
+
+### 2. 检查资源是否加载
+
+```typescript
+const resMgr = context.resourceManager
+const str = await resMgr.getStringByName('app_name')
+hilog.info(0x0000, 'I18N', 'String value: %{public}s', str)
+```
+
+### 3. 检查资源目录是否存在
+
+```typescript
+// 在 DevEco Studio 中
+// File > Project Structure > Module > Resources
+// 查看 supportedLanguages 是否与实际目录匹配
+```
+
+---
+
+## 错误代码速查
+
+| 错误现象 | 可能原因 | 解决方案 |
+|---------|---------|---------|
+| 切换语言后 UI 不更新 | 未触发重建 | 增加 `@Local refreshKey` 或 `@ObservedV2 LocaleModel` 的 `@Trace refreshKey` 字段并改变 ID |
+| `$r()` 引用报错 | string.json 中 key 不存在 | 检查 key 拼写 |
+| setPreferredLanguage 不生效 | 未声明 supportedLanguages | 在 module.json5 中声明 |
+| 英文资源不加载 | 目录名错误 | 使用 `en` 而非 `en_US` |
+| 日文显示乱码 | 文件编码错误 | 确保文件是 UTF-8 编码 |
+| 图片不切换 | 文件名不一致 | 不同语言目录图片文件名相同 |