@harmonyos-arkts/d2h 0.0.0-stage → 0.1.0

package/skills/arkts-i18n/references/static-vs-dynamic.md

@@ -0,0 +1,242 @@
+# 纯静态 vs 动态语言切换方案
+
+> 基于代码仓实际实现的方案对比分析
+
+---
+
+## ✅ 已验证：纯静态国际化方案
+
+> 基于代码仓实际实现（95%+ 使用静态引用，无动态语言切换）
+
+### 方案特点
+
+**代码仓实践**：
+- ✅ 依赖系统语言自动匹配
+- ✅ 95%+ 使用 `$r('app.string.xxx')` 静态引用（270+ 处）
+- ✅ 少数场景使用 `resourceManager.getStringByNameSync()` 动态获取
+- ❌ 未实现运行时语言切换
+- ⚠️ module.json5 未配置 `supportedLanguages`
+
+**优点**：
+- ✅ 实现简单，无需复杂状态管理
+- ✅ 性能最优（编译时确定资源路径）
+- ✅ 自动跟随系统语言，用户无感知
+- ✅ 代码量少，维护成本低
+
+**缺点**：
+- ⚠️ 无法在应用内动态切换语言
+- ⚠️ 用户需要通过系统设置更改语言
+- ⚠️ 需要重启应用才能看到语言变化
+
+### 适用场景
+
+| 场景 | 是否适用 | 说明 |
+|------|---------|------|
+| 跟随系统语言 | ✅ 推荐 | 无需额外开发，自动适配 |
+| 单一市场应用 | ✅ 推荐 | 简化实现，降低复杂度 |
+| 国际化应用（无切换需求）| ✅ 推荐 | 依赖系统设置即可 |
+| 需要应用内切换语言 | ❌ 不适用 | 需实现动态方案 |
+| 需要记住用户语言偏好 | ❌ 不适用 | 需实现状态持久化 |
+
+---
+
+## 实现要点
+
+### 1. 资源文件组织
+
+**方案 1：base/ 放中文**（代码仓采用，适合单一市场）
+
+```
+entry/src/main/resources/
+├── base/element/string.json       # 中文（主要市场）
+└── en_US/element/string.json      # 英文
+```
+
+**工作原理**：
+- 系统中文 → 找不到 zh 目录 → 使用 base/ → 显示中文 ✅
+- 系统英文 → 找到 en_US → 显示英文 ✅
+
+**方案 2：创建 zh_CN 目录**（标准做法，适合国际化应用）
+
+```
+entry/src/main/resources/
+├── base/element/string.json       # Fallback（英文或其他）
+├── zh_CN/element/string.json      # 中文
+└── en_US/element/string.json      # 英文
+```
+
+**工作原理**：
+- 系统中文 → 找到 zh_CN → 显示中文 ✅
+- 系统英文 → 找到 en_US → 显示英文 ✅
+- 其他语言 → 无匹配 → 使用 base/ → 显示 Fallback 语言 ✅
+
+**关键规范**：
+- ✅ base/ 和 en_US/（或 zh_CN/）的 string.json **行数完全一致**
+- ✅ 所有字符串 key 在不同语言文件中**完全对应**
+- ✅ 使用 `en_US/` 而非 `en/`（精确区域划分）
+
+### 2. 静态资源引用（主流方式，95%+）
+
+**使用场景**：Button 文本、Text 标签、Title 标题等固定文本
+
+```typescript
+// ✅ 推荐：在 build() 中使用静态引用
+Text($r('app.string.app_name'))
+Button($r('app.string.confirm'))
+.title($r('app.string.settings_title'))
+Image($r('app.media.logo'))
+```
+
+**工作原理**：
+1. 编译时扫描所有 `$r()` 引用
+2. 根据系统语言自动选择资源文件：
+   - 中文环境 → `base/element/string.json`
+   - 英文环境 → `en_US/element/string.json`
+3. 运行时自动加载匹配的资源
+
+### 3. 动态资源获取（少数场景，<5%）
+
+**使用场景**：需要动态处理字符串（如占位符替换、复数处理）
+
+```typescript
+// ✅ 基于代码仓 ColumnsDialog.ets:22
+const context = getContext(this)
+const resourceManager = context.resourceManager
+const str = resourceManager.getStringByNameSync('dialog_column')
+```
+
+**何时使用**：
+- 需要替换占位符（如 `"%d 列"` → `"3 列"`）
+- 需要处理复数（如 `"1 column"` vs `"2 columns"`）
+- 需要根据字符串内容判断语言环境
+
+### 4. module.json5 配置（可选）
+
+```json5
+{
+  "module": {
+    "name": "entry",
+    "type": "entry",
+    "description": "$string:module_desc",  // ✅ 使用 $string 引用
+    "abilities": [
+      {
+        "name": "EntryAbility",
+        "description": "$string:EntryAbility_desc",
+        "label": "$string:EntryAbility_label"
+      }
+    ]
+    // ⚠️ 当前代码仓未配置 supportedLanguages
+    // 如需配置，可添加：
+    // "supportedLanguages": ["zh-Hans", "en"]
+  }
+}
+```
+
+**配置说明**：
+- ✅ `description` 和 `label` 也支持 `$string` 引用
+- ⚠️ `supportedLanguages` 不是必需字段（当前代码仓未配置）
+- 💡 配置后可明确告知系统应用支持的语言
+
+---
+
+## 对比动态语言切换方案
+
+| 特性 | 纯静态方案 | 动态切换方案 |
+|------|-----------|------------|
+| **实现复杂度** | ✅ 低（仅资源文件） | ⚠️ 高（需状态管理 + UI 刷新） |
+| **性能** | ✅ 最优（编译时确定） | ⚠️ 中等（运行时切换） |
+| **用户体验** | ✅ 一致（自动跟随系统） | ⚠️ 需手动切换 |
+| **维护成本** | ✅ 低 | ⚠️ 高 |
+| **适用场景** | ✅ 大多数应用 | ⚠️ 特殊需求（如学习类应用） |
+| **代码量** | ✅ 少（仅配置） | ⚠️ 多（需实现切换逻辑） |
+
+---
+
+## 当前代码仓选择分析
+
+**选择方案**：纯静态方案 + `en_US/` 目录
+
+**选择原因**：
+
+1. **简单可靠**
+   - ✅ 无需维护复杂的状态管理
+   - ✅ 自动跟随系统语言，用户无感知
+   - ✅ 代码量少，维护成本低
+
+2. **性能最优**
+   - ✅ 编译时确定资源路径
+   - ✅ 无运行时语言切换开销
+   - ✅ 资源加载效率高
+
+3. **需求匹配**
+   - ✅ 代码仓只需支持中英文
+   - ✅ 无应用内切换语言需求
+   - ✅ 跟随系统语言即可满足需求
+
+**使用 `en_US/` 而非 `en/` 的原因**：
+
+| 方案 | 优点 | 缺点 | 代码仓选择 |
+|------|------|------|-----------|
+| `en/` | 简单，适配所有英文区域 | 无法区分不同区域（US/GB/AU） | ❌ 未选择 |
+| `en_US/` | 精确区域划分，可扩展 | 目录稍多 | ✅ 已选择 |
+
+**结论**：
+- ✅ 代码仓选择 `en_US/` 是为了精确区域划分和未来扩展性
+- ✅ 纯静态方案满足当前需求，无需引入动态切换的复杂性
+- 💡 如果未来需要动态切换，可参考 `dynamic-language-switch.md` 实现
+
+---
+
+## ⚠️ 未验证：动态语言切换
+
+以下代码基于 HarmonyOS 理论 API，需要查证官方文档：
+
+```typescript
+import { resourceManager } from '@kit.LocalizationKit'
+import { common } from '@kit.AbilityKit'
+
+// ⚠️ 未验证 - 需要确认 API 是否存在
+async function switchLanguage(lang: string): Promise<void> {
+  try {
+    const context = getContext(this) as common.UIAbilityContext
+    const resMgr = context.resourceManager
+    
+    // ⚠️ 以下两个 API 需要查证官方文档
+    await resMgr.setPreferredLanguage([lang])
+    const langs = await resMgr.getPreferredLanguage()
+    
+    console.log(`Switched to: ${langs[0]}`)
+  } catch (err) {
+    console.error(`Failed to switch language: ${err}`)
+  }
+}
+```
+
+**替代方案**（如 API 不存在）：
+- 方案 1：引导用户到系统设置修改语言
+- 方案 2：应用内维护语言状态，手动切换资源
+
+---
+
+## ✅ 已验证：资源文件结构
+
+基于 `entry/src/main/resources/` 目录结构：
+
+```
+resources/
+├── base/
+│   └── element/
+│       └── string.json          # 中文（996 行）
+├── en_US/
+│   └── element/
+│       └── string.json          # 英文（996 行）
+├── dark/
+│   └── element/
+│       └── color.json           # 深色模式颜色
+└── rawfile/                     # 原始文件
+```
+
+**验证结果**：
+- ✅ base 和 en_US 的 string.json 行数一致（996 行）
+- ✅ 两个文件的 key 完全对应
+- ✅ 使用 en_US 而非 en（精确区域划分）

package/skills/arkts-i18n/references/v1-compat.md

@@ -0,0 +1,244 @@
+# V1 兼容写法参考（仅老项目查阅）
+
+> ⚠️ **本项目锁 ArkTS V2**。本文档为 **V1 历史参考**（`@Component / @State / @StorageLink / @Prop / @Watch` 等），仅用于阅读老代码或迁移老项目时查阅。
+>
+> **新代码请使用 V2 装饰器**：参阅 [`SKILL.md`](../SKILL.md)、[`dynamic-language-switch.md`](./dynamic-language-switch.md)、[`code-examples.md`](./code-examples.md)（已升级 V2）。
+>
+> i18n 相关 API（`resourceManager` / `intl` / `$r('app.string.xxx')` / `setPreferredLanguage` / `getPreferredLanguage` / `onLanguageConfigurationUpdate`）在 V1/V2 之间**完全不变**，本文仅记录"持有 locale / refreshKey 状态"的 V1 装饰器写法。
+
+---
+
+## V1 / V2 速查（仅 i18n 相关）
+
+| V1 | V2 |
+|---|---|
+| `@Component` | `@ComponentV2` |
+| `@State refreshKey: number = 0` | `@Local refreshKey: number = 0` |
+| `@StorageLink('currentLanguage') lang: string = 'zh'` | 先定义 `@ObservedV2 LocaleModel`，然后 `@Local locale = AppStorageV2.connect(LocaleModel, 'locale', () => new LocaleModel())!`，访问 `this.locale.currentLanguage` |
+| `@StorageLink('languageRefreshKey') key: number = 0` | 同上，访问 `this.locale.refreshKey` |
+| `@Prop currentColumns: number = 3` | `@Param @Once currentColumns: number = 3`（只读） |
+| `@Prop currentColumns: number = 3`（子可改本地副本） | `@Param currentColumns: number = 3`（不带 @Once） |
+| `@Watch('lang') onLangChange()` | `@Monitor('lang') onLangChange(m: IMonitor)` |
+| `AppStorage.setOrCreate('refreshKey', n)` | `localeStore.refreshKey = n`（直接改 @Trace 字段） |
+| `PersistentStorage.persistProp('currentLanguage', 'zh')` | `PersistenceV2.globalConnect({ type: LocaleModel, key: 'locale', defaultCreator: () => new LocaleModel() })` |
+
+---
+
+## V1 简单实现（单页面语言切换）
+
+```typescript
+import { resourceManager } from '@kit.LocalizationKit'
+import { common } from '@kit.AbilityKit'
+
+@Entry
+@Component
+struct LanguageSwitchDemoV1 {
+  private context = getContext(this) as common.UIAbilityContext
+  @State private currentLanguage: string = 'zh'
+  @State private refreshKey: number = 0
+
+  async switchLanguage(lang: string): Promise<void> {
+    const resMgr = this.context.resourceManager
+    await resMgr.setPreferredLanguage([lang])
+    this.currentLanguage = lang
+    this.refreshKey++
+  }
+
+  build() {
+    Column() {
+      Text($r('app.string.welcome'))
+      Button('English').onClick(() => this.switchLanguage('en'))
+    }
+    .id('lang_' + this.refreshKey)
+  }
+}
+```
+
+**升级到 V2**（参考 [`dynamic-language-switch.md`](./dynamic-language-switch.md) 的"基本实现"）：
+- `@Component` → `@ComponentV2`
+- `@State` → `@Local`
+- 其他 API 调用不变
+
+---
+
+## V1 全局状态共享（@StorageLink 多 key 写法）
+
+```typescript
+// V1：散落的 key（拼写易错、无类型保护）
+class LanguageStateV1 {
+  @StorageLink('currentLanguage') currentLanguage: string = 'zh'
+  @StorageLink('languageRefreshKey') refreshKey: number = 0
+
+  async setLanguage(context: common.UIAbilityContext, lang: string): Promise<void> {
+    const resMgr = context.resourceManager
+    await resMgr.setPreferredLanguage([lang])
+    this.currentLanguage = lang
+    this.refreshKey++
+  }
+}
+
+// V1 设置页面
+@Entry
+@Component
+struct SettingsPageV1 {
+  @StorageLink('currentLanguage') currentLanguage: string = 'zh'
+  @StorageLink('languageRefreshKey') refreshKey: number = 0
+
+  build() {
+    Column() {
+      Text(`Current: ${this.currentLanguage}`)
+    }
+    .id('settings_' + this.refreshKey)
+  }
+}
+
+// V1 任意页面
+@Entry
+@Component
+struct AnyPageV1 {
+  @StorageLink('languageRefreshKey') refreshKey: number = 0
+
+  build() {
+    Column() {
+      Text($r('app.string.any_string'))
+    }
+    .id('page_' + this.refreshKey)
+  }
+}
+```
+
+**问题**：
+- key 拼写错误（如 `'lanugageRefreshKey'`）静默失效
+- 无类型保护（值是 Object）
+- 字段加减需改多处
+
+**V2 重构**（推荐，见 [`dynamic-language-switch.md`](./dynamic-language-switch.md) 的"全局 LocaleModel"段）：
+- 单一 `@ObservedV2 LocaleModel` 封装所有 locale 状态
+- 任意组件 `@Local locale = AppStorageV2.connect(LocaleModel, 'locale', () => new LocaleModel())!`
+- 访问 `this.locale.currentLanguage` / `this.locale.refreshKey`
+- 编译期类型检查 + IDE 重命名安全
+
+---
+
+## V1 子组件接收只读 Prop
+
+```typescript
+@Component
+export struct ColumnsDialogV1 {
+  @Prop currentColumns: number = 3        // V1：单向只读（API 12+ 必须初始化）
+
+  build() {
+    Text(`Columns: ${this.currentColumns}`)
+  }
+}
+```
+
+**V2 等价写法**（见 [`code-examples.md`](./code-examples.md) 的 V2 ColumnsDialog）：
+
+```typescript
+@ComponentV2
+export struct ColumnsDialog {
+  @Param @Once currentColumns: number = 3  // V2：单向只读（编译期检查）
+
+  build() {
+    Text(`Columns: ${this.currentColumns}`)
+  }
+}
+```
+
+---
+
+## V1 监听语言变化（@Watch）
+
+```typescript
+@Component
+struct PageV1 {
+  @StorageLink('currentLanguage') @Watch('onLangChange') currentLanguage: string = 'zh'
+
+  onLangChange(propName: string): void {
+    console.info(`Language changed: ${this.currentLanguage}`)
+    // 副作用：埋点、清缓存等
+  }
+
+  build() { Column() { Text($r('app.string.hello')) } }
+}
+```
+
+**V2 等价**：
+
+```typescript
+@ComponentV2
+struct Page {
+  @Local locale: LocaleModel = AppStorageV2.connect(
+    LocaleModel, 'locale', () => new LocaleModel()
+  )!
+
+  @Monitor('locale.currentLanguage')
+  onLangChange(monitor: IMonitor): void {
+    console.info(`Language changed: ${this.locale.currentLanguage}`)
+    // 副作用
+  }
+
+  build() { Column() { Text($r('app.string.hello')) } }
+}
+```
+
+---
+
+## V1 持久化语言偏好（PersistentStorage.persistProp）
+
+```typescript
+// V1：双层模式（AppStorage + Preferences）
+PersistentStorage.persistProp('currentLanguage', 'zh')
+
+@Component
+struct PageV1 {
+  @StorageLink('currentLanguage') currentLanguage: string = 'zh'
+  // 修改 currentLanguage 自动落盘 + UI 刷新
+}
+```
+
+**V2 等价**（一站式）：
+
+```typescript
+@ObservedV2
+class LocaleModel {
+  @Trace currentLanguage: string = 'zh'
+}
+
+@ComponentV2
+struct Page {
+  @Local locale: LocaleModel = PersistenceV2.globalConnect({
+    type: LocaleModel,
+    key: 'app_locale',
+    defaultCreator: () => new LocaleModel()
+  })!
+  // 修改 this.locale.currentLanguage 自动落盘 + UI 刷新（无需双层）
+}
+```
+
+---
+
+## V1 → V2 迁移建议
+
+1. **先升级 SKILL.md / 主参考的代码模板**（已完成 — 见本目录其他文件）
+2. **逐文件迁移老代码**：从最常用的 LanguageSettings / Settings 页面开始
+3. **抽取 LocaleModel**：把所有 `@StorageLink('currentLanguage' | 'languageRefreshKey' | ...)` 整合到一个 `@ObservedV2 LocaleModel` 类
+4. **替换装饰器**：
+   - `@Component` → `@ComponentV2`
+   - `@State` → `@Local`
+   - `@StorageLink('xxx') xxx: T = default` → `@Local locale: LocaleModel = AppStorageV2.connect(LocaleModel, 'locale', () => new LocaleModel())!`，访问 `this.locale.xxx`
+   - `@Prop` → `@Param @Once`（只读）/ `@Param`（可改本地副本）
+   - `@Watch` → `@Monitor`
+   - `PersistentStorage.persistProp` → `PersistenceV2.globalConnect`
+5. **同 struct 内不混用 V1/V2 装饰器**（编译报错）
+
+---
+
+## 跨文档参考
+
+- [`SKILL.md`](../SKILL.md) — V2 优先决策树与陷阱
+- [`dynamic-language-switch.md`](./dynamic-language-switch.md) — V2 完整动态切换模板
+- [`code-examples.md`](./code-examples.md) — V2 ColumnsDialog 实战示例
+- [`common-pitfalls.md`](./common-pitfalls.md) — V2 i18n 避坑
+- 跨 Skill：[`arkts-mvvm-architecture/SKILL.md`](../../arkts-mvvm-architecture/SKILL.md) — 当前工程的 V2 状态管理、组件和架构规范

package/skills/arkts-i18n/scripts/audit_i18n_completeness.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# audit_i18n_completeness.sh — i18n cross-locale key consistency audit.
+#
+# 单一职责：检测跨 locale 的 string.json / plural.json / strarray.json 的 key 一致性。
+#   base 的全部 key 必须在每个 language locale（zh_CN / en_US / ...）都存在；
+#   mode locale（dark / horizontal / vertical 等）按差异覆盖即可，豁免。
+#
+# 资源 value 内的 [TODO: translate] / 裸 TODO 检测不在本脚本范围；调用者必须在
+# 当前请求范围收尾时另行扫描并把发现项返回为 unresolved。本脚本只管跨 locale 完整性。
+#
+# 用法（由 arkts-i18n 任务完成后自调，不被其他 skill 跨引用）：
+#   bash audit_i18n_completeness.sh \
+#       --project-root <abs> \
+#       --output-json docs/i18n-audit.json
+#
+# 退出码：
+#   0  全 PASS（key 一致）
+#   1  有 key_missing FAIL 项
+#   2  脚本错误（参数缺失等）
+#
+# 输出 JSON 结构：
+#   {
+#     "locales": ["base", "zh_CN", ...],
+#     "language_locales": ["zh_CN", ...],      # 参与 key 一致性校验的 locale
+#     "mode_locales": ["dark", ...],            # 豁免 locale
+#     "key_count_per_locale": { "base": N, "zh_CN": N, ... },
+#     "findings": [
+#       { "type": "key-missing", "locale": "zh_CN", "key": "home_feed", "base_locale": "base", "suggested_action": "..." }
+#     ],
+#     "summary": { "key_missing": N, "FAIL": N }
+#   }
+
+set -euo pipefail
+
+PROJECT_ROOT=""
+OUTPUT_JSON=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --project-root)   PROJECT_ROOT="$2"; shift 2 ;;
+        --output-json)    OUTPUT_JSON="$2"; shift 2 ;;
+        --help|-h)
+            grep '^#' "$0" | head -40
+            exit 0
+            ;;
+        *)
+            echo "unknown arg: $1" >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+    echo "error: --project-root required" >&2
+    exit 2
+fi
+
+# Resolve to absolute path; on Git Bash use `pwd -W` to get Windows-style for Python interop
+if pwd -W >/dev/null 2>&1; then
+    PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd -W)"
+else
+    PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd)"
+fi
+OUTPUT_JSON="${OUTPUT_JSON:-/dev/stdout}"
+
+RESOURCES_ROOT="$PROJECT_ROOT/entry/src/main/resources"
+
+if [[ ! -d "$RESOURCES_ROOT" ]]; then
+    echo "error: resources root not found: $RESOURCES_ROOT" >&2
+    exit 2
+fi
+
+# ─── Python helper: cross-locale key consistency only ───────────────────────
+PY_HELPER=$(cat <<'PYEOF'
+import json, os, sys
+
+project_root = sys.argv[1]
+output_path = sys.argv[2]
+resources_root = os.path.join(project_root, 'entry', 'src', 'main', 'resources')
+
+# 仅对翻译类 element 文件做校验
+TRANSLATION_ELEMENT_FILES = {'string.json', 'plural.json', 'strarray.json'}
+
+# Mode locale 豁免（按差异覆盖即可）
+MODE_LOCALES = {'dark', 'light', 'horizontal', 'vertical', 'land', 'port'}
+
+def is_language_locale(name: str) -> bool:
+    if name in MODE_LOCALES:
+        return False
+    if '_' in name:
+        return True
+    if 2 <= len(name) <= 3 and name.isalpha():
+        return True
+    return False
+
+# Collect locales + key sets
+locales = []
+key_per_locale = {}
+for entry in sorted(os.listdir(resources_root)):
+    locale_dir = os.path.join(resources_root, entry)
+    elem_dir = os.path.join(locale_dir, 'element')
+    if not os.path.isdir(elem_dir):
+        continue
+    if entry in ('rawfile', 'profile'):
+        continue
+    locales.append(entry)
+    key_per_locale[entry] = set()
+    for fname in os.listdir(elem_dir):
+        if fname not in TRANSLATION_ELEMENT_FILES:
+            continue
+        fpath = os.path.join(elem_dir, fname)
+        try:
+            with open(fpath, encoding='utf-8') as f:
+                data = json.load(f)
+        except Exception:
+            continue
+        for items in data.values():
+            if not isinstance(items, list):
+                continue
+            for item in items:
+                if isinstance(item, dict) and 'name' in item:
+                    key_per_locale[entry].add(item['name'])
+
+# Language vs mode locales
+language_locales = [l for l in locales if is_language_locale(l)]
+mode_locales = [l for l in locales if l in MODE_LOCALES]
+
+# Key consistency check: base keys must exist in every language locale
+findings = []
+base_locale = 'base' if 'base' in key_per_locale else (locales[0] if locales else None)
+if base_locale:
+    base_keys = key_per_locale[base_locale]
+    for locale in language_locales:
+        if locale == base_locale:
+            continue
+        missing = base_keys - key_per_locale[locale]
+        for k in sorted(missing):
+            findings.append({
+                "type": "key-missing",
+                "locale": locale,
+                "key": k,
+                "base_locale": base_locale,
+                "suggested_action": f"Add key `{k}` to {locale}/element/<file>.json with locale-appropriate value.",
+            })
+
+summary = {
+    "key_missing": len(findings),
+    "FAIL": len(findings),
+}
+
+out = {
+    "locales": locales,
+    "language_locales": language_locales,
+    "mode_locales": mode_locales,
+    "key_count_per_locale": {l: len(k) for l, k in key_per_locale.items()},
+    "summary": summary,
+    "findings": findings,
+}
+
+if output_path == '/dev/stdout':
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+else:
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+    with open(output_path, 'w', encoding='utf-8') as f:
+        json.dump(out, f, ensure_ascii=False, indent=2)
+    print(f"i18n audit complete: {output_path}")
+    print(f"  locales={locales}  language={language_locales}  mode={mode_locales}")
+    print(f"  FAIL={summary['FAIL']} (key_missing={summary['key_missing']})")
+
+sys.exit(1 if summary["FAIL"] > 0 else 0)
+PYEOF
+)
+
+python3 -c "$PY_HELPER" "$PROJECT_ROOT" "$OUTPUT_JSON"