国际化问题并不总以乱码或崩溃出现。有时候法语页面看起来也能正常打开，只有一条权限说明仍是中文。测试人员换回简体中文再进入同一页，问题就消失了。原因可能不是组件写错，而是 fr_FR 资源目录少了一条同名键：系统会按照资源匹配规则尝试回退，页面“能显示”反而遮住了翻译遗漏。

这篇把检查点放在发布流水线前，而不是等待用户切换语言后再发现。演示工程叫 LocaleGate，任务编号 L10N-309，覆盖 base、en_US、fr_FR 三套资源目录。业务定义八个必须显式翻译的键：app_name、home_title、search_hint、permission_explain、confirm_button、cancel_button、privacy_entry、offline_hint。构造样例中 base 为 8/8、en_US 为 8/8、fr_FR 为 7/8，只缺 permission_explain，所以发布门禁显示 BLOCKED。这是项目自定义的质量规则，不是平台对所有应用的硬性审核判定。

一、把资源回退与翻译完整性分开

ArkUI 的 $r('app.string.xxx') 访问工程资源。资源按设备状态、语言等限定词匹配，匹配不到目标项时可能回退到基础资源。这个机制保障 UI 在部分资源缺失时仍可用，但“可用”与“已经按计划本地化”完全不是一回事。假如隐私、权限或付费说明被回退成另一种语言，使用者可能无法准确理解含义。

工程目录中 entry/src/main/resources/base/element/string.json 作为基础文案，en_US/element/string.json 和 fr_FR/element/string.json 作为本项目声明支持的目标语言。并不是所有地区码都需要创建目录；只检查明确在发布清单中支持的语言。若产品尚未承诺法语服务，不能用缺少法语翻译来判断它不合格。本例故意把 fr_FR 写进清单，是为了演示构建门禁如何阻止漏翻。

第一段代码展示运行界面的引用方式。权限说明、确认和取消都从资源读取，避免把中文文本直接嵌进 ArkTS。注释中的资源名必须与 JSON 的 name 字段一字不差；错误的别名无法通过后面的静态扫描得到正确保护。

@Entry
@Component
struct PermissionIntroPage {
  @State expanded: boolean = true;
  build() {
    Column({ space: 16 }) {
      Text($r('app.string.home_title')).fontSize(22)
      if (this.expanded) {
        Text($r('app.string.permission_explain')).fontSize(16)
        Row({ space: 12 }) {
          Button($r('app.string.confirm_button'))
            .onClick(() => { this.expanded = false; })
          Button($r('app.string.cancel_button'))
            .onClick(() => { this.expanded = false; })
        }
      }
      Text($r('app.string.privacy_entry'))
      Text($r('app.string.offline_hint'))
    }.padding(20).width('100%')
  }
}

组件只决定如何展示文案，不在 UI 里进行构建期检查。@State expanded 控制示意说明区域，和资源是否存在没有直接关系。即使 fr_FR 缺少一条说明，系统仍可能通过基础资源显示一段文字。若仅凭页面没有空白就宣布多语言通过，会错过最应审查的内容。对权限说明这类高风险句子，最好再安排真正理解目标语言的人员复核意思是否准确；脚本最多能确认键存在、值非空，并不能判断翻译质量。

二、一个足够简单的静态门禁

这里采用 Node.js 的文件系统 API 扫描 string.json，因为构建脚本本来就擅长读取源码，而不是应用运行时再探查其资源包。检查器不依赖未公开的 HarmonyOS 系统接口；它是与 ArkTS 工程配套的构建工具。对于 CI 环境，Node 版本由项目已有工具链约束，这里不虚构与 DevEco Studio 对应的具体版本号。

string.json 的典型结构是对象内有 string 数组，数组元素带 name 和 value。工程中的多语言目录可能还携带其他资源类型，脚本此处只扫描 string，不把图片、复数资源或格式化占位符检查混入第一版。检查路径从工程根目录解析；不要指向构建产物中的压缩文件，因为构建期我们需要的是源资源是否齐全。

第二段代码是门禁的核心。读取失败直接判定为阻断；语言必须与清单一致；缺失的 permission_explain 会打印固定格式错误，便于在构建日志里搜索。

// tools/check-locales.mjs（从项目根目录运行）
import fs from 'node:fs';
import path from 'node:path';
const root = 'entry/src/main/resources';
const locales = ['base', 'en_US', 'fr_FR'];
const keys = ['app_name', 'home_title', 'search_hint', 'permission_explain',
  'confirm_button', 'cancel_button', 'privacy_entry', 'offline_hint'];

function loadStrings(locale) {
  const file = path.join(root, locale, 'element', 'string.json');
  const json = JSON.parse(fs.readFileSync(file, 'utf8'));
  if (!Array.isArray(json.string)) throw new Error(`${locale} missing string[]`);
  return new Map(json.string.map(item => [item.name, item.value]));
}
let missingTotal = 0;
for (const locale of locales) {
  try {
    const dict = loadStrings(locale);
    const missing = keys.filter(key =>
      typeof dict.get(key) !== 'string' || dict.get(key).trim() === '');
    missingTotal += missing.length;
    console.info(`L10N-309 ${locale} ${keys.length - missing.length}/${keys.length}`);
    missing.forEach(key => console.error(`L10N-309 ${locale} MISSING ${key}`));
  } catch (error) {
    missingTotal++;
    console.error(`L10N-309 ${locale} READ_FAILED ${String(error)}`);
  }
}
console.info(`L10N-309 publish=${missingTotal ? 'BLOCKED' : 'READY'} missing=${missingTotal}`);
if (missingTotal > 0) process.exitCode = 1;

脚本的返回码比彩色日志更重要：退出状态非零，CI 才有机会停止后续打包或提交步骤。READ_FAILED 不是缺少某一个键，因此日志不会冒充已经知道具体缺失项。Map 只是检测工具的数据结构；如果资源文件内存在相同 name 的重复声明，Map 会覆盖前一个值，所以正式使用还应增加重复键检测。这个不足必须写明，不能称它已经覆盖所有国际化风险。

图里的构造日志固定为 L10N-309 fr_FR MISSING permission_explain 与 L10N-309 publish=BLOCKED missing=1。当编辑人员补全翻译、确认语义后，重新执行脚本才可把发布状态改成 READY。不要在 UI 按钮里提供无审计依据的“忽略错误并发布”。这属于工程内部质量门禁，不代表任何平台的审核豁免或审核结果。

三、让构建失败真正挡住下一步

最常见的假门禁是只打印警告，却没有把非零退出码传给上层构建任务。有人在控制台看见红色 MISSING，仍继续上传，因为 CI 只检查了打包命令是否成功。正确的整合方式是把扫描器放在打包、签名、上传之前，并把它作为必须成功的独立步骤。你可以在现有自动化环境中调用 node tools/check-locales.mjs，不必改动 HarmonyOS 运行时。

第三段代码不依赖特定 CI 服务，给出一个 Node.js 入口来组织失败传播。它只是辅助入口，不替代 DevEco Studio 的实际构建；当检查失败，后续发布动作不应被执行。

// tools/prepublish.mjs
import { spawnSync } from 'node:child_process';
const checked = spawnSync(process.execPath, ['tools/check-locales.mjs'], {
  encoding: 'utf8', stdio: 'inherit'
});
if (checked.error || checked.status !== 0) {
  console.error('L10N-309 gate=BLOCKED; skip package/publish');
  process.exitCode = 1;
} else {
  console.info('L10N-309 gate=READY; invoke the configured build pipeline');
  // 实际构建命令由项目 CI 配置，不在示例中臆造。
}

将工具独立为 check-locales.mjs 和 prepublish.mjs，并不是为了多造一层封装，而是让开发者可以在本地检查，也能让 CI 读取相同退出码。注意示例不会自动开始真实打包：它只交代如何传递阻断语义。若公司流程使用固定语言审核表，还可以把缺键列表导出为机器可读的 JSON，再由发布负责人签署修复状态；但这不是本文代码必须实现的部分。

四、示例报告、回退策略和盲区

以 L10N-309 的构造输入运行上述逻辑，报告应依次列出 base 8/8、en_US 8/8、fr_FR 7/8，最后 BLOCKED missing=1。手机界面配图展示的不是实际法语翻译，而是一张本地化自检面板：能看到风险键、目标语言和下一步动作。这样和 IDE 图形成互补——IDE 负责指出缺键的来源，手机面板负责说明发布决策。两个画面都不代表应用市场已经作出审核裁决。

只用字符串键数作为衡量标准，会遇到几个边界。首先，有些语言故意复用品牌名或标准术语，脚本只能判断非空，不能判断复用是否合理。其次，有些文案包含 %s、%d 等占位符，目标语言即使存在相同键，也可能因占位符数量不同导致格式化错误；上线前应该补充占位符结构比对。再次，fr_FR 与 fr 是否需要同时支持，取决于产品实际发布语言和资源目录设计，不能由工具擅自扩充。

还有一个容易被忽略的点：资源文件不等于应用市场元数据。应用内 string.json 即便全部完整，应用商店的名称、简介、隐私链接、截图说明仍然可能存在语言不一致。它们需要单独的上架材料核对；本门禁没有访问应用市场后台，也无法替代平台政策检查。

调试这种问题不需要虚构一次真实的审核被拒经历。先构造缺键样例，观察构建脚本给出的缺失项目；把那条键恢复，检查退出码是否从 1 变成 0；再切换设备语言观察 UI 是否按实际限定词回退。如果检查器通过但显示仍不符合预期，就继续看资源限定词匹配、安装包是否包含最新文件，以及页面是否把文案缓存为硬编码字符串。这三条路径比泛泛地清理缓存更可重复。

文章的结论不是“缺一个翻译一定被拒审”，而是：应用运行时的资源回退不能代替发布前的显式覆盖率检查。通过自定义构建门禁把遗漏变成可定位、可复现的阻断结果，再把语义正确性留给人工核验，能够降低多语言页面的交付风险。BLOCKED、8/8 和 7/8 均为构造示例，本轮未运行真实审核、未进行 DevEco 项目编译，三张配图是合成演示界面。

资料参考：

• 华为 Stage 模型资源分类与访问（资源目录与 $r）：https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V2/resource-categories-and-access-0000001544463977-V2
• 华为国际化和本地化概述：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/i18n-l10n-V13
• 华为开发者文档中心：https://developer.huawei.com/consumer/cn/doc/