发布前检查多语言素材很容易被一句“英文可以回退到默认资源”安慰。确实资源系统会按限定词匹配资源匹配不到时存在基础资源兜底机制。但这并不代表用户看到的内容就正确更不代表所有带格式参数的字符串都还能安全显示。一个列表标题回退成中文可能只是体验问题一个表示数量的%d被英文译文误改成%s可能让调用代码的参数契约与文案脱节。这次做一个离线工具示例LocaleGateLab任务LOC-1010-13输入是开发工程entry/src/main/resources下三个示例string.json资源文件。我们不调用AppGallery后台接口也不假设华为审核一定按这份脚本的规则判定。目标是开发团队在上传构建物之前自己先生成一份可复核的差异报告基准资源26个键简体中文26个键英文文件26条记录但只有25个唯一键缺少1项格式签名不匹配2项重复命名1项合计4条阻断项。最后状态固定为RELEASE_HOLD平台审核标记NOT_RUN。一、把展示回退和交付完整度划成两条线华为公开的资源目录文档描述了resources/base和带限定词资源目录的关系element/string.json采用string数组存储name/value条目ArkUI侧通常通过$r(app.string.xxx)引用。本文检查的是工程源码里实际出现的资源定义不是调用一次系统资源获取后再从屏幕截图逆推出所有资源键。为什么要绕开“实际渲染成功”的判断因为资源存在回退机制。假设英文资源少了album_selected页面仍可能显示base目录中的值用户看不到空白自动截图比对也未必能发现语言混杂。对海外交付而言这恰恰是风险缺失项被回退掩盖QA误以为多语言覆盖完整。本文把“运行能回退”和“交付是否有翻译缺口”分别记账避免一个结果推导另一个结果。另一个差别在于键名重复。假设英文string.json有两条同名app_title而某段代码先用Map索引后面的条目会覆盖前面的条目。如果审计发生在Map构造之后重复的证据已经消失。一个更安全的读入过程必须先保留原始记录数量和每个键出现次数再建立后续查询索引。这也是我们将rawEntries26与uniqueKeys25同时输出的原因。本例只讨论string.json这种文本资源。并未覆盖plural.json数量规则、strarray.json顺序、多媒体资源限定词、日期与货币本地化、右到左布局。开发者不应把一份字符串检查器当成全部国际化验收也不应把它描述为华为发布政策它只是团队自己可运行的静态质量门禁。二、先锁定资源事实而不是先展示红色总数目录约定为entry/src/main/resources/base/element/string.json、zh_CN/element/string.json和en_US/element/string.json。每个文件必须能解析成含string数组的JSON。为便于复核演示样本中的base有26个唯一键zh_CN同样26个en_US保留26条原始记录其中app_title出现两次导致只有25个唯一键而album_selected完全缺失。格式漂移则集中在photo_count与storage_size。这里不把译文相似度当成判断依据只比较格式占位符签名基准photo_count需要整数格式英文误成字符串格式基准storage_size需要字符串格式英文误成整数格式。这两条就是第二类错误和文件缺失、键重复分别计数。最终1214不会因总条目恰好都是26而放行。如果让团队成员只看文件个数和字段数量很容易得到“26对26一切齐全”的错觉。真正要检查的是三层含义同名键是否覆盖、每个目标语言的唯一键集合是否与基准集合一致、同键格式参数是否兼容。三层检查顺序也影响错误归因遇到重复键不能只拿最后一个value继续做格式比较并宣称没有问题重复本身应单独留下阻断证据。这份脚本的输入模型很窄但边界更清晰所有比较都基于本地文件快照不修改资源、不自动翻译、不调用在线词库不根据机器环境猜测当前用户语言。建议实际使用时把构建分支、提交SHA、扫描文件SHA附到报告元数据里本文的示例数据只显示任务号与报告数量并不编造GitHub或Git提交记录。三、先读原始数组重复证据才不会被覆盖Node.js使用内置fs/promises.readFile读取文件、JSON.parse解析内容都是普通本地工具能力不是HarmonyOS设备端API。这里不要把电脑上的Node脚本写成运行在手机模拟器中的系统服务UI画面只是展示这份离线审计结果的一张概念稿。第一段代码读入一个语言文件返回rawCount、去重后的键表和重复项集合。它在读取每个元素时都进行形态检查避免把undefined或者对象value混到字符串占位符分析中。示例没有引入JSON5解析器因为资源文件是string.json不是oh-package.json5两者不可混为一谈。import{readFile}fromnode:fs/promises;asyncfunctionloadStringResource(file){consttextawaitreadFile(file,utf8);constbodyJSON.parse(text);if(!Array.isArray(body.string))thrownewError(string[] missing);constvaluesnewMap();constduplicatesnewSet();for(constrowofbody.string){if(!row||typeofrow.name!string||!row.name||typeofrow.value!string){thrownewError(invalid resource row);}if(values.has(row.name))duplicates.add(row.name);elsevalues.set(row.name,row.value);}return{rawCount:body.string.length,values,duplicates:[...duplicates].sort()};}读入阶段不需要做“最后一个覆盖前一个”的取舍。一旦出现重复键后续发布判断就应进入阻断状态将第一个值保留只是为了能继续生成报告。假设app_title分别翻译成两个完全不同的句子工具应该报告相同的重复键而不应擅自判断哪个译文代表产品经理的真实意图。文件损坏或string不是数组与一般缺少单个资源键的性质不同。本文给它更高的失败等级直接标记输入不可审计。真实CI里可以用独立退出码区分解析失败、规则失败和I/O失败避免团队在脚本读取不到文件时还拿到一份假“0问题”的空报告。这个区别很重要尤其是资源目录路径拼写错误时。四、格式参数不是普通文案必须比较签名有些资源值包含%d和%s这类参数标记数量、文件大小、用户名等页面会用变量填入。如果只比较译文长度完全无法发现类型漂移。本案例只检查一组明确定义的格式签名按出现顺序提取%d和%s对比同名基准值与目标语言值的签名。生产环境还要按目标系统的实际格式化规则处理带位置编号、转义百分号、宽度修饰和本地化格式不能把这段轻量正则当成完整的printf语法解析器。第二段代码把格式检查写成可以单测的函数。这里的%d代表整数位置、%s代表字符串位置是业务的资源约定任何混用都应先由研发或本地化负责人确认。脚本不负责猜测需要填入的运行时实参类型只负责防止同一个资源键在两个语言版本里悄悄改了类型签名。functionformatSignature(value){return[...value.matchAll(/%(?:\d\$)?[ds]/g)].map(matchmatch[0]).join(|);}functioncompareLocale(base,local){constmissing[...base.values.keys()].filter(key!local.values.has(key)).sort();constplaceholderDrift[...base.values.keys()].filter(keylocal.values.has(key)).filter(keyformatSignature(base.values.get(key))!formatSignature(local.values.get(key))).sort();return{missing,placeholderDrift,duplicates:local.duplicates};}有一个值得单独说明的陷阱某些文案翻译时需要交换参数顺序比如英文先写文件名、后写数量而另一种语言的顺序相反。本文的检测器将位置编号作为签名的一部分它可能把合法的顺序变化误报。此时应该升级检查规则允许显式位置参数并对照调用实参验证类型而不是简单关闭格式检查。静态门禁是帮助评审找风险不是替代语言专家确认句法。同时%出现在折扣描述或数学公式中时也未必代表格式占位符。实际工程最好将使用占位符的资源键列为独立白名单或者使用符合平台格式规则的解析器。本文用photo_count与storage_size两个固定字段来演示目的是让失败证据可复现、数字可核对而不是声称全项目所有格式都由一个正则准确识别。五、先保留回退证据再决定能否发布对于缺失的album_selected资源系统可能从base取到可展示的文本。这是运行时显示能力我们的审计状态则必须记录fallbackDetected1并明确目标语言覆盖存在缺口。如果产品设计允许特定键保留默认语言应有显式、带原因和到期时间的豁免清单。不能让“系统能找到值”自动等同于“业务许可混用语言”。这里坚持两种状态分离。DISPLAY_FALLBACK_POSSIBLE只描述资源解析层的可能路径不是静态扫描器实际运行了设备语言切换。RELEASE_HOLD则是本地工具自己的质量门禁判断四条阻断项存在时拒绝生成“可以交付”标记。若业务后来设豁免也应该把豁免的具体键列入报告而不是直接改统计数字掩盖原始差异。示例UI里的基准键数26、中文26、英文原始26、英文唯一25看起来有点琐碎却是防止误判的关键。用任何一个单值概括都会丢失信息。缺失一项和重复一项恰好抵消了原始长度正式开发时就可能产生一份“数量全相同”的误导报告。报告必须同时显示条目数和唯一键数。在上传应用素材的工作流里这份资源检查最适合置于构建产物形成之前。它可以让团队提前发现明显错位的资源定义但不能证明某个平台后台会接受该应用更不能替代真机语言切换测试、审核说明准备或法律地区要求。文章标题中的“发布前阻断”指我们自己的质量门禁不是官方强制审核规则。六、脚本主程序如何形成可回放的结论为了不让读者只看到若干函数却不知道最终怎么判定第三段代码把三个资源读取、目标比较和汇总输出连起来。以本轮示例的资源目录为根检查zh_CN和en_US两个目录并将阻断计数汇总。当前案例中中文资源没有问题英文资源有1缺失、2漂移、1重复所以总阻断4最终RELEASE_HOLD。import{join}fromnode:path;asyncfunctionrunAudit(root){constbaseawaitloadStringResource(join(root,base/element/string.json));constzhawaitloadStringResource(join(root,zh_CN/element/string.json));constenawaitloadStringResource(join(root,en_US/element/string.json));constzhIssuescompareLocale(base,zh);constenIssuescompareLocale(base,en);constblockers[...zhIssues.missing,...zhIssues.placeholderDrift,...zhIssues.duplicates,...enIssues.missing,...enIssues.placeholderDrift,...enIssues.duplicates].length;conststateblockers0?RELEASE_READY:RELEASE_HOLD;return{taskId:LOC-1010-13,base:base.values.size,zh_CN:zh.values.size,en_US_raw:en.rawCount,en_US_unique:en.values.size,issues:enIssues,blockers,state,platformReview:NOT_RUN};}这个主程序返回结构化数据不会在错误时吞掉异常。输入文件不存在或JSON解析失败应该让上层CI把任务判为AUDIT_ERROR而不是误报RELEASE_READY。真正接入持续集成时还需要固定Node版本、检查工作目录、设置时间上限、保留标准输出和错误输出并让退出码与报告状态一致。另一个工程要求是确定性对相同的输入文件报告键名、问题数组排序和数量必须相同。这样才能在PR里比较差异不会因为Map迭代和系统文件顺序不同而出现无意义噪声。sort()不是表面排版它让审计结果有利于版本追踪。若后来增加多语言目录建议按显式配置清单扫描避免自动遍历把rawfile或不支持的限定词也当成语言文件。七、模拟诊断页不应该伪装成审核平台LocaleAuditPage表现汇总LocaleIssuePage表现明细。两个页面都是为了写作而制作的应用演示UI没有真正把Node脚本嵌入HarmonyOS设备运行。生产工具更可能作为DevEco构建前脚本或CI任务执行再把JSON结果交给可视化前端。它们共享任务IDLOC-1010-13表示的是同一份本地规则夹具。汇总页的状态应保持RELEASE_HOLD四个阻断问题来自三种不同原因album_selected缺失、photo_count与storage_size格式漂移、app_title重复。平台审核NOT_RUN必须明确显示。UI如果为了好看把背景做成大绿勾或写成“已通过华为审核”就越过了证据边界。我们宁可用红色阻断状态解释具体差异也不能把模型里的好看数字包装成真实平台结果。诊断页要保留每个问题对应的resource文件路径、资源键和期待签名。尤其是重复键问题不应只显示一份值而隐藏原始两条记录。若后续人工批准某一处非严格翻译报告应包含审批理由、风险等级与豁免期限但本Demo没有豁免字段也没有把任何问题自动改为通过。八、对工具做六种反向测试第一种把英文album_selected补齐再运行一次。预期缺失计数从1降为0但另外两种问题仍存在总阻断从4变3状态依旧RELEASE_HOLD。这条测试用来发现一种常见偷懒实现只要缺失数为0就宣告通过忽略重复键和格式漂移。正确的状态判定应该聚合全部规则结果。第二种将app_title重复项删除只保留一条真实译文。英文原始条目由26变25唯一键仍是25重复数从1变0。注意原始条目“减少”不等于质量变差反而是消除歧义。若看板仅以rawEntries增长作为质量指标就会把这次正确修复标记成回退。第三种把photo_count英文值从%s改回%d。格式漂移从2降为1但storage_size仍需单独修改。这可以测试实现是否按键逐项比较而不是看到英文文件存在某一个%d就认为整个文件的数字占位符已经齐全。第四种删除整个英文文件或将其string改成对象。预期脚本报输入不可审计而不产生missing0。真实交付时这是一条阻断级别更高的错误不能由base资源回退来“消除”。因为我们无法确认目标语言完整性也无法验证构建时的实际资源组织方式。第五种在base中新增一个必须翻译的新资源键。如果英文没有同步缺失数应自动增加如果中文也没有同步两个目标目录都需要显示问题来源。脚本不能依赖写死的26个键名否则随着开发新增功能质量门禁反而会越来越脱离真实工程。第六种故意让所有资源值都包含格式不支持的复杂标记例如%1$d、%2$s或者转义百分号组合。此时当前简化解析器只能报告它观察到的签名不能断言最终资源调用安全。应该把这类样本移交更完整的格式解析测试并增加ArkTS侧的代表性调用验证。工具的可信度来自明确范围而非宣称覆盖无穷情况。九、脚本与应用界面的责任不能颠倒Node.js脚本运行在开发机或CI而HarmonyOS应用显示由编译后的资源系统处理。两者能互相提供信息但不能相互替代。静态报告能指出资源数组结构错误却无法证明真正界面宽度是否足以容纳德语长词截图检查能发现截断却未必看出隐藏在base回退后的英文缺键。两类验收应该形成互补。构建前工具负责人负责把资源快照、问题数组和错误退出码做稳定页面负责人负责检查$r使用与可见文案是否匹配测试人员负责在目标设备语言设置下检查渲染、格式参数和无障碍读屏。所谓“发布准备好了”只能由多层证据共同支撑不能让某个页面上的RELEASE_READY单独作结论。这也是本篇不选择“自动修改译文”的原因。发现storage_size类型不一致工具不知道译者原意是否涉及单位变化也不知道调用端是否已经修改了参数类型。如果擅自把%d改回%s有可能掩盖真正的代码协议变更。稳妥的动作是把两侧字符串、来源路径和调用位置交给负责人确认再进行资源与代码同步修改。同时还要注意配置目录本身随SDK与项目模板可能存在差异。文中沿用官方资源目录文档所描述的resources/base和限定词目录的组织方式实际工程应以当前DevEco项目结构及对应SDK为准。工具不应该在发现未知目录时武断删除它也不要把某个版本的指南路径当成所有未来工程的唯一格式。十、如何解释本轮报告的“结果”这次在本地Node.js测试夹具中约定的统计合同是base26、zh_CN26、en_US原始26、英文唯一25missing1、placeholderDrift2、duplicate1、blockers4状态RELEASE_HOLDplatformReviewNOT_RUN。报告提供可定位的四条错误足以说明这组构造数据不应该由我们的本地流程放行。它不是应用市场的真实审核结果也不是对全项目国际化程度的评级。从工程维护的角度我更在意的是这份报告是否能够让下一位开发者独立复现打开三个JSON资源文件、运行同一版检查器、得到同样的问题键与数量。只要保留这个最小可复现条件前端UI以后换成表格、终端、CI注释或PR机器人都不影响判断逻辑。如果只保留一张漂亮的结果图过几周就很难说清楚四条问题从哪里来。还需要提醒资源回退正常不等于语言覆盖完整静态检查全绿也不等于真机排版和地区规则通过。现阶段我们可以确定的是检查器对预设样本的分类结果以及所用资源定义结构与官方基础文档对应不能声称“已经上架”“审核通过”或“所有HarmonyOS 7设备均表现一致”。把这道门禁放进团队流程之前应先添加针对真实项目资源的只读模式再经过设计、翻译和研发共同确认规则。上线时将结果分成解析失败、资源覆盖缺口、格式兼容风险和人工豁免四种状态。不要把RELEASE_HOLD简单翻译成“软件错误”它只是把本来可能埋在发布后的问题提前暴露给人处理。官方参考华为开发者《资源分类与访问》https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V2/resource-categories-and-access-0000001544463977-V2Stage资源base、限定词和string.json结构资料版本可能与目标SDK模板不同及当前版本《oh-package.json5》2026-10-08https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hmos-oh-package-json5区分模块和工程配置仅作为交付工程背景。示例的四条门禁是应用团队自定义规则并非AppGallery审核规定所有截图为示意真实商店审核、设备多语言验证均未执行。
