移动端多语言资源维护

开发者维护源 JSON，脚本同步生成 UTS 语言包与三端原生名称资源，无需逐个平台改名。界面语言仍为 zh-CN、en-US，默认及最终回退为 zh-CN；桌面名称独立按系统语言匹配。

环境与快速开始

需要 Python 3.9+（终端可执行 python3）及项目要求的 Node.js/pnpm，无额外 Python 依赖。以下命令均在仓库根目录执行，Windows 也需确保 python3 指向 Python 3。

pnpm mobile:i18n check
pnpm mobile:i18n sync --dry-run
pnpm mobile:i18n sync
pnpm mobile:i18n check

check 不写文件，资源过期或输入非法时返回非零退出码；sync --dry-run 只显示将变更的文件及差异。sync 先校验全部输入，再写入有变化的文件，重复执行无额外修改。

源文件与生成文件

源文件（相对于 apps/ak-mobile）	用途
`locale/zh-CN.json`	完整简体中文界面文案
`locale/en-US.json`	与中文 key、占位符一致的英文文案
`i18n/native.json`	默认、简体、繁体安装名称

src/core/i18n/generated/catalog-entries.uts 和原生名称资源由脚本维护。不要直接修改生成的名称；原生配置中的其他资源、权限和图标可以继续按原有方式维护，脚本只更新名称相关字段。UTS 生成器保留每批 100 条的分块，适配原生编译。

新增、更新与批量维护文案

pnpm mobile:i18n set common.save --zh "保存" --en "Save"

set 新增或更新一个语义 key，同时更新两套 JSON 并同步生成资源。中英文参数均必填，不自动翻译。建议使用 feature.action 形式的 key。

批量修改时直接编辑两套 JSON，再执行 sync --dry-run 和 sync。例如修改问候语时，两种文案都必须包含 {name}。仅修改其中一种语言的文字可以，但两套 key 和占位符必须一致。脚本保留已有 key 顺序，不自动删除未使用文案。

在页面中使用

复用现有单例 akI18n；不要另建实例，否则不会跟随应用语言设置。

import { akI18n } from '@/src/core/i18n/ak-i18n.uts';

const saveLabel = akI18n.t('common.save', null);
const params = new Map<string, string>();
params.set('name', 'Alex');
const greeting = akI18n.t('home.greeting', params);

上述示例展示调用和参数格式。需实时切换的页面文案应在模板或响应式计算中调用，例如：

<text>{{ akI18n.t('common.save', null) }}</text>

修改桌面应用名称

编辑 apps/ak-mobile/i18n/native.json：

{
  "appName": {
    "default": "AppKernia",
    "zh-Hans": "应核",
    "zh-Hant": "應核"
  }
}

执行 pnpm mobile:i18n sync，同步 Android 字符串、iOS plist/本地化名称及 HarmonyOS 字符串，并更新安装默认名称。

简体中文显示“应核”，繁体中文显示“應核”，其他语言默认使用“AppKernia”。这些原生语言标记不代表新增了繁体业务语言包，也不会修改用户的 App 内语言偏好。

名称修改必须重新打包安装正式包或自定义基座，热更新无法更新桌面名称。 操作见移动端打包。系统语言匹配和桌面显示需在新包上验证简体、繁体（台湾/香港）、英文及其他语言，源码检查通过不代表真机验收通过。

常见错误与修复

错误	修复
`duplicate key`	删除同一 JSON 内重复的 key，保留正确翻译
`expected non-empty text`	把空值、纯空白或非字符串改为完整文案
`key mismatch`	按错误提示补齐两套语言包缺少的 key
`placeholder mismatch`	确保两种翻译的 `{name}` 等占位符名称一致
`Generated resources are stale`	检查源 JSON 后执行 `pnpm mobile:i18n sync`

非法输入在写入前报错，不会写入半套翻译。Mobile 静态检查与统一打包入口会检查生成资源是否过期；打包不会自动同步源码。旧 check-i18n-catalogs.py 命令仍可使用，但只处理 UTS 语言包，日常维护建议使用统一入口。

返回移动端开发。

#移动端多语言资源维护

#环境与快速开始

#源文件与生成文件

#新增、更新与批量维护文案

#在页面中使用

#修改桌面应用名称