默认数据也要做国际化：稳定 ID、legacyNames 与旧版本兼容

一个容易被漏掉的多语言场景假设应用首次启动时自动创建早睡、喝水、运动、阅读、冥想、学习如果直接把这些中文保存到Habit.name用户切换到英语后界面其他内容变成英文默认习惯却仍是中文。如果为了切换语言而批量改名又会遇到用户可能已经手动把“早睡”改成其他名字中英文名称可能与用户自定义名称冲突旧版本保存过英文或日文快速添加需要判断某个默认习惯是否已经存在。这说明“默认数据”不是普通翻译文案而是带身份的持久化实体。一、默认习惯定义需要四类信息项目定义exportinterfaceStarterHabit{resourceName:string;storedName:string;legacyNames:string[];icon:string;color:string;}示例{resourceName:starter_sleep,storedName:sleep-early,legacyNames:[早睡,Sleep early,早寝],icon:moon_z,color:#5E7CE2}各字段职责字段作用resourceName从当前语言资源获取显示名称storedName新版本写入磁盘的稳定身份legacyNames识别旧版本曾保存的翻译文本icon/color默认视觉配置二、创建时只保存稳定 storedNameexportfunctionmakeStarterHabit(definition:StarterHabit):Habit{constnow:numberDate.now();return{id:newId(),name:definition.storedName,icon:definition.icon,color:definition.color,isActive:true,createdAtMillis:now,updatedAtMillis:now,archivedAtMillis:0};}无论首次启动时界面是中文、英文还是日文磁盘中都保存sleep-early语言变化不会修改业务身份。三、显示时再根据资源本地化先判断某个 Habit.name 是否对应默认习惯privatestarterDefinition(name:string):StarterHabit|undefined{returnSTARTER_HABITS.find((starter:StarterHabit)starter.storedNamename||starter.legacyNames.includes(name));}然后显示privatelocalizedHabitName(habit:Habit):string{conststarterthis.starterDefinition(habit.name);returnstarter?this.named(starter.resourceName):habit.name;}因此磁盘sleep-early 中文显示早睡 英文显示Sleep early 日文显示早寝用户自定义习惯找不到 StarterDefinition就原样显示。四、legacyNames 解决什么问题假设早期测试版本已经把“早睡”直接写进磁盘。升级后如果只识别sleep-early这个旧习惯会被当作普通自定义习惯切到英文仍显示中文快速添加可能再创建一个 sleep-early默认图标迁移逻辑无法识别它。加入legacyNames:[早睡,Sleep early,早寝]可以在不清空旧数据的情况下继续识别。legacyNames是兼容层不应该成为新写入格式。五、快速添加去重也必须使用同一身份规则privatehasStarterHabit(starter:StarterHabit):boolean{returnthis.habits.some((habit:Habit)habit.namestarter.storedName||starter.legacyNames.includes(habit.name));}快速添加前调用constalreadyExiststhis.hasStarterHabit(starter);if(!alreadyExists){this.habits[...this.habits,makeStarterHabit(starter)];}显示和去重必须共享同一套身份判断否则页面认为它是默认习惯添加逻辑却认为它不存在。六、用户真正改名后应该发生什么如果用户把“早睡”改成“23:00 前睡觉”新名称不在legacyNames中。之后它应被视为用户自定义名称切换语言不自动翻译显示用户输入原文快速添加是否允许再次添加默认“早睡”属于产品决策。当前轻量模型通过name是否匹配默认集合来推断身份简单但存在边界用户恰好自定义了一个名为“早睡”的习惯会被识别为默认项只修改图标但未改名时保存的本地化名称可能进入兼容路径默认项与用户项没有显式类型字段。更成熟的模型可以增加interfaceHabit{id:string;customName:string;starterKey:string;// ...}规则变为starterKey 有值且 customName 为空 → 使用资源翻译 customName 有值 → 显示用户名称这样身份不再依赖名称碰撞。七、首次初始化为什么要有 seededStarterHabits只判断habits.length 0不够。用户可能主动删除全部习惯此时数组为空但应用不应该在下次启动时又自动创建六个默认习惯。项目同时检查if(this.habits.length0||this.settings.seededStarterHabits){return;}首次引导结束后设置next.seededStarterHabitstrue;删除全部数据时也保持这个标记为 true确保“删除”结果不会被自动初始化抵消。八、默认数据应该在隐私同意前创建吗不应该。即使默认习惯不是用户输入创建它也意味着应用开始写入本地状态。项目在用户同意隐私并完成引导后才执行privateasyncfinishOnboarding():Promisevoid{this.seedStarterHabits();// 保存引导状态}这样首次隐私门禁之前不会偷偷改变用户数据空间。九、新增默认习惯需要同步哪些地方新增一个默认习惯时至少要完成在STARTER_HABITS添加稳定storedName添加中英日legacyNames三份string.json增加相同resourceName选择可用系统图标 Key验证快速添加去重验证首次引导初始化验证语言切换验证用户改名后保持原文运行资源 Key 校验脚本。项目通过 Node 脚本比较三种语言的 Key 集合防止只补一种语言。十、默认数据兼容测试矩阵测试数据中文英文日文sleep-early早睡Sleep early早寝旧值早睡早睡Sleep early早寝旧值早寝早睡Sleep early早寝自定义23:00 睡觉原文原文原文另外测试旧值存在时快速添加不重复删除默认习惯后不会自动复活删除全部数据后重启仍为空新增资源 Key 三种语言一致导出 JSON 保留稳定身份。总结默认数据国际化的核心原则是显示名称与稳定身份分离新数据只保存稳定 Key旧翻译文本通过兼容集合识别显示和去重共享身份规则用户自定义名称不自动翻译自动初始化要有“一次性完成”标记模型复杂后应增加显式 starterKey。只要默认内容会写入磁盘它就不再是单纯的界面文案而是需要版本兼容的数据协议。本文案例来自“心晴手记MoodMemoir”HarmonyOS 版的六个默认习惯与中英日切换。参考资料HarmonyOS Localization Kit应用本地化