HarmonyOS 应用开发之多语言国际化：zh_CN/en_US 限定词与 string.json 资源体系详解

多语言国际化zh_CN/en_US 限定词与 string.json 资源体系一、引言国际化i18n是多设备短视频应用走向更多用户的基本功。一个覆盖直板机、平板与 PC 的应用若把文案硬编码在代码里每一次文案调整、每新增一种语言都要翻遍全部源码——这既是维护负担也是质量隐患。HarmonyOS 提供了一套与深色模式同构的资源限定词机制文案声明在string.json中通过zh_CN、en_US等语言限定词目录提供多语言版本代码中一律用$r(app.string.xxx)引用系统按设备语言环境自动匹配切换语言零代码。multi-short-video 工程在五个产品模块、四个特性模块与公共模块中全面落地了这一机制。本文以首页products/default、评论multishortvideocomment、个人作品页multishortvideoindividual三处真实文案为例讲解 string.json 的资源定义、$r引用、格式化占位符与兜底策略。二、zh_CN/en_US 限定词目录与 string.json 资源定义国际化的载体是语言限定词目录。以评论模块为例其资源目录结构为features/multishortvideocomment/src/main/resources/ ├── base/element/string.json # 默认文案兜底中文 ├── zh_CN/element/string.json # 简体中文 ├── en_US/element/string.json # 美式英语 ├── dark/element/color.json # 深色颜色与语言正交 └── base/media/ # 图标等媒体资源base目录承担兜底职责当设备语言不匹配任何限定词目录时系统取base中的取值。因此工程把base的文案定义为中文zh_CN与base内容一致en_US提供英文——即便未来新增小语种未覆盖的文案也能正确回退到中文。限定词之间用中划线连接可组合例如dark/zh_CN同时限定主题与语言本文与深色模式文章51可以互相印证。string.json 的格式为name value数组。name 是编译期键必须与语言无关推荐英文下划线风格value 是展示文案。评论模块的中英文定义如下// features/multishortvideocomment/src/main/resources/zh_CN/element/string.json节选 { string: [ { name: leave_comment, value: 写评论 }, { name: author, value: 作者 }, { name: reply, value: 回复 }, { name: view_all_reply, value: 查看全部回复 }, { name: nothing_more, value: 暂时没有更多了 } ] }// features/multishortvideocomment/src/main/resources/en_US/element/string.json节选 { string: [ { name: leave_comment, value: leave a comment }, { name: author, value: author }, { name: view_all_reply, value: view all replies }, { name: nothing_more, value: Theres nothing more for now } ] }注意en_US中可以省略reply——未定义时自动回退base的中文回复。工程保留它是因为英文文案与中文不同故显式声明。限定词目录只写差异、base 兜底是控制多语言维护成本的关键。base与zh_CN内容一致的约定还有一个工程理由IDE 与构建系统在资源冲突时会有提示但不会阻止两份文件内容漂移例如某次需求只改了 base 忘记同步 zh_CN。工程建议通过脚本或 lint 规则强制二者 key 集合一致把兜底目录真正变成默认语言的备份而不是放任它成为第二事实源。同理dark颜色目录与base颜色目录的 key 集合也应保持一致任何新增颜色都要双份声明——这与第 51 篇文章中深色资源的治理纪律完全同构。三、$r(app.string.xxx) 引用方式UI 层引用文案统一使用$r(app.string.资源名)。$r返回一个Resource对象可传递给 Text 组件的文本参数、TextInput 的 placeholder、Tabs 的标题等。评论页features/multishortvideocomment/src/main/ets/view/Comment.ets中的真实引用Text($r(app.string.author)) // 作者徽标 Text($r(app.string.reply)) // 回复按钮 Text($r(app.string.view_all_reply)) // 查看全部回复 Text($r(app.string.nothing_more)) // 列表底部暂时没有更多了 TextInput({ text: this.commentInput!!, placeholder: $r(app.string.leave_comment), // 输入框占位文案 controller: this.controller })个人作品页features/multishortvideoindividual/.../components/Individual.ets同样统一引用$r(app.string.author_id)国家地理/National Geographic、$r(app.string.likes)获赞/likes、$r(app.string.search_placeholder)搜索/Search、$r(app.string.introduction)点击添加介绍…等页签标题通过 ViewModel 注入IndividualTabsViewModel.etsthis.individualTabsData.push(new MSVDataModel(works, $r(app.string.ind_work))); // 作品/work this.individualTabsData.push(new MSVDataModel(privacy, $r(app.string.ind_private))); // 私密/private this.individualTabsData.push(new MSVDataModel(collection, $r(app.string.ind_collection))); // 收藏/collection this.individualTabsData.push(new MSVDataModel(like, $r(app.string.ind_like))); // 喜欢/like首页 TabBar 文案定义在products/default/.../viewmodel/MainTabsViewModel.ets中中英文对照如下资源名zh_CNen_UShome_title首页Homefriend_title朋友Friendmessage_title消息Messagerecommend_title推荐Recommendfollow_title关注Follow这里有个重要观察$r引用是跨模块的——评论模块、个人页模块、公共模块的文案都通过各自模块的 string.json 定义引用路径统一为app.string.*系统按当前模块资源 → AppScope 全局资源的顺序解析。这也要求各模块资源名全局不冲突是第 55 篇文章代码规范强调资源命名纪律的原因之一。四、格式化字符串与占位符评论数、点赞数这类数字 文案的场景不能简单拼接字符串——不同语言对数字与名词的顺序、复数形式要求各异。正确做法是在 string.json 中声明带占位符的模板用$r(app.string.xxx, 参数)在引用时注入。视频模块的评论标题即为此范例features/multishortvideoadaptivevideo/src/main/resources/zh_CN/element/string.json{ name: comment_title, value: 评论(%d) }// features/multishortvideoadaptivevideo/src/main/resources/en_US/element/string.json { name: comment_title, value: comment(%d) }播放器控件层引用时注入数值features/multishortvideoadaptivevideo/.../view/AdaptiveVideo.ets第 322 行// bindSheet 半模态标题显示评论(5) title: { title: $r(app.string.comment_title, 5) }%d是十进制整数占位符系统按当前语言环境格式化后替换。这样中英文环境下数字与文案的相对位置、标点都由各语言自己的模板决定翻译时可以自由调整结构而不影响代码。除了%d鸿蒙资源还支持%s字符串、%f浮点数等占位符多参数按序对应。选择整句翻译还是模板占位符取决于数字与文案的排列关系是否跨语言稳定。以视频模块的发布时间为例中英文的时间表达差异明显2小时前 vs two hours ago工程选择整句翻译——release_time资源直接声明整句避免数字单位跨语言排列错位只有当数字与文案顺序在所有语言中都一致时才使用占位符。判断标准很简单把翻译交给译者时模板中保留的占位符越少出错概率越低。五、运行时语言切换与兜底策略运行时语言切换完全由系统承担用户在系统设置中修改语言后应用进程内资源引用自动指向新语言目录无需重启应用或手动刷新——前提是所有文案都通过$r引用且没有把字符串缓存在普通变量中。工程中Comment.ets、Individual.ets等组件每次 build 时都实时求值$r(app.string.xxx)天然支持热切换。兜底策略则要回答语言不齐时怎么办。限定词匹配的完整规则是先按限定词匹配程度排序匹配项越多越优先全部不匹配时回退base。因此base必须完整且兜底可用工程中 base 即中文能覆盖全部文案en_US等语言目录允许缺项缺项回退 base但缺项会造成半中半英的混排体验。工程中products/default/.../resources/en_US/element/string.json的mine_title值仍为我的中文未翻译就是一个需要排查的真实案例——en_US存在同名键但值未翻译系统不会回退到其他目录只能靠审查发现。这正是国际化质量治理的切入点要么该语言目录完整覆盖要么干脆不建目录靠 base 兜底最怕建了目录却不翻全。从实现层面看语言资源还影响module.json5中的应用名与 Ability 标签products/default的DefaultAbility_label、module_desc也走了$r(app.string.xxx)国际化系统桌面、任务卡片上展示的应用名会随语言变化。也就是说国际化不是页面文案的局部工程而是从桌面图标、任务卡片到页面内容的全链路统一。做国际化自查时除了页面遍历还要把桌面名称、通知栏文案、权限弹窗文案一并纳入检查范围。六、多模块文案的协同管理工程有五个产品模块、四个特性模块加一个公共模块每个模块维护自己的base/zh_CN/en_US三份 string.json跨模块文案的协同由此成为治理重点。工程的实际分工是公共文案放 common业务文案放所属特性模块产品定制文案放产品模块。公共模块common/multishortvideobase只声明了一条empty_text暂无内容/No content供各特性模块的空态组件复用评论、个人页、视频页的文案各自收口在本模块内leave_comment、ind_work、comment_title等首页 TabBar 的文案则因各产品形态不同而放在产品模块——default 的home_title/recommend_title即是如此tv 产品若有差异化文案只需在自己的资源目录覆盖。这种就近声明避免了公共资源命名空间的膨胀也符合products → features → common三层架构的职责边界。协同管理还需处理两个跨模块细节。其一是资源命名空间的唯一性$r(app.string.xxx)在运行时按当前模块 → AppScope顺序解析两个模块声明同名 key 时当前模块内的引用优先命中自己那份——这既是能力也是陷阱若想跨模块复用公共文案应引用公共模块明确暴露的资源而不是碰运气。其二是资源表与代码的同步新增文案后要同步检查zh_CN/en_US两份文件CI 可加脚本比对 key 集合发现缺项即失败对应前文目录完整性纪律代码审查时也可用$r(app.string.)的全局搜索快速核对每个引用点都有对应资源。对于需要按设备能力裁剪文案的场景工程还可以组合限定词与断点同一 key 在不同形态产品模块中给出不同 value配合WidthBreakpointType的代码分支做到文案与布局、交互同步适配。总之多模块国际化的本质是把文案即代码的观念升级为文案即资源定义在资源层、引用在代码层、差异由系统层解决。七、总结与最佳实践多语言国际化在本工程中沉淀为四条最佳实践文案零硬编码所有展示文案进string.json代码一律$r(app.string.xxx)引用占位符场景用$r(app.string.comment_title, 5)注入参数不手工拼接。base 兜底 语言目录只写差异base 放默认语言本工程为中文zh_CN/en_US按需声明新语言目录未覆盖的文案自动回退控制维护成本。name 与语言无关资源名统一英文下划线风格leave_commentvalue 才允许写中文避免把语言写进编译期键。目录完整性审查语言目录要么建全、要么不建对同名键值未翻译如 en_US 中mine_title残留中文这类隐患做专项排查可借助资源比对脚本在 CI 中拦截。遵循这四条新增页面时只需建资源 → 写引用两步多语言与多设备第 05 篇文章的资源规范共同构成工程化文案管理的地基。