#Mobile localization maintenance

Edit source JSON and generate UTS catalogs and native launcher resources with one command. UI locales remain zh-CN and en-US, with zh-CN as the default and final fallback. Launcher names follow native system language selection independently.

#Requirements and quick start

Use Python 3.9+ available as python3, plus the project's Node.js and pnpm versions. No additional Python dependencies are needed. Run all commands from the repository root. On Windows, ensure python3 resolves to Python 3 too.

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

check is read-only and exits nonzero for invalid inputs or stale resources. sync --dry-run prints changed paths and diffs without writing. sync validates all inputs before writing changed files; running it again produces no further changes.

#Source and generated resources

The tool maintains src/core/i18n/generated/catalog-entries.uts and native name resources. Edit the source configuration to rename the app. Other native resources, permissions, and icons remain independently maintainable; only name-related fields are updated. The UTS generator retains 100-entry chunks for native compiler compatibility.

#Add, update, and batch-edit translations

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

set adds or updates one semantic key in both catalogs and synchronizes generated resources. Both translations are required; no automatic translation is performed. Use semantic keys such as feature.action.

For batch edits, edit both JSON catalogs and run sync --dry-run, then sync. Both versions of a greeting must retain the same {name} placeholder. Editing text in only one locale is allowed as long as keys and placeholders still match. Existing key order is preserved; unused keys are not automatically removed.

#Use translations in a page

Reuse the existing akI18n singleton. Creating another instance would disconnect it from the app's locale selection.

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);

This demonstrates the call and parameter format. For live locale switching, call translations from a template or reactive computation:

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

#Change the launcher name

Edit apps/ak-mobile/i18n/native.json:

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

Run pnpm mobile:i18n sync to update Android strings, iOS plist/localized names, HarmonyOS strings, and the default installation name.

Simplified Chinese uses “应核”; Traditional Chinese uses “應核”; other languages default to “AppKernia”. These native language tags do not add a Traditional Chinese UI catalog or change the user's in-app locale preference.

Rebuild and reinstall the release app or custom base after renaming. Hot updates cannot update launcher names. See mobile packaging. Validate the new package on devices using Simplified Chinese, Traditional Chinese (Taiwan/Hong Kong), English, and another language. Source checks do not constitute device acceptance.

#Troubleshooting

Invalid inputs fail before files are written. Mobile static checks and the unified packaging entry point reject stale generated resources; packaging does not automatically synchronize source files. The legacy check-i18n-catalogs.py command remains available for UTS catalogs only; use the unified CLI for routine maintenance.

Return to mobile development.