Internationalization (i18n) workflow and standards for managing translations. Use when: (1) Adding new user-facing text, (2) Creating new components with text, (3) Reviewing code for i18n compliance. Features: Key naming conventions, sync checking, hardcoded string detection, translation workflow.
npxskills add iofficeai/aionui--skill i18nLoading…
Standards and workflow for internationalization. All user-visible text must use i18n.
Announce at start: "I'm using i18n skill to ensure proper internationalization."
Before doing any i18n work, always read src/common/config/i18n-config.json to get the current list of supported languages and modules. Never assume a fixed number — languages and modules may have been added or removed since this skill was written.
cat src/common/config/i18n-config.json
This file is the single source of truth. All scripts, runtime code, and this workflow depend on it.
src/common/config/i18n-config.json # Single source of truth: languages, modules
src/renderer/i18n/
├── index.ts # i18next configuration
├── i18n-keys.d.ts # AUTO-GENERATED — do not edit manually
└── locales/
├── <lang>/ # One directory per language in i18n-config.json
│ ├── index.ts # Barrel import for all modules
│ ├── common.json # One JSON per module in i18n-config.json
│ ├── conversation.json
│ └── ...
└── ...
referenceLanguage in i18n-config.json (currently en-US)supportedLanguages array — read the file to get the current listmodules array — read the file to get the current listKeys use namespaced dot notation in code: t('module.key') or t('module.nested.key').
Inside each module JSON file, keys can be flat or nested:
// common.json — flat keys
{
"send": "Send",
"cancel": "Cancel",
"copySuccess": "Copied"
}
// cron.json — nested keys
{
"scheduledTasks": "Scheduled Tasks",
"status": {
"active": "Active",
"paused": "Paused"
}
}
In code:
t('common.send'); // flat key in common.json
t('cron.status.active'); // nested key in cron.json
copySuccess, scheduledTasksstatus.active, actions.pausecommon.json: save, cancel, delete, confirm, etc.| Suffix | Usage |
|---|---|
title | Section/page titles |
placeholder | Input placeholders |
label | Form labels |
success / error | Status messages |
confirm | Confirmation dialogs |
empty | Empty state messages |
tooltip | Tooltip text |
src/common/config/i18n-config.jsonGet the current language list and module list. Do not skip this step.
Before adding a new key, search for similar existing keys:
grep -r "keyword" src/renderer/i18n/locales/en-US/
Reuse common.* keys when possible.
Match the module to the feature area. If no module fits, consider whether a new module is needed (see "Adding a New Module" below).
CRITICAL: Every new key must be added to every locale in supportedLanguages. Use this checklist for each key:
en-US/<module>.json — reference language (added in Step 3)zh-CN/<module>.json — addedzh-TW/<module>.json — addedsrc/common/config/i18n-config.json → supportedLanguages — addedA key missing from even one locale will cause node scripts/check-i18n.js to fail in CI.
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { t } = useTranslation();
return <button>{t('common.save')}</button>;
}
Run these two commands in order — both must pass before committing:
bun run i18n:types # Step A: regenerate i18n-keys.d.ts from reference locale
node scripts/check-i18n.js # Step B: validate structure, keys, and type sync
i18n:types must be run before check-i18n.js — the check validates the generated filecheck-i18n.js exits with errors (❌), fix them before proceedingcheck-i18n.js exits with warnings only (⚠️), review but may proceedi18n-keys.d.tssrc/common/config/i18n-config.json → modules array<module>.json in every locale directory (read supportedLanguages to know which)index.tsbun run i18n:types to regenerate type definitionsnode scripts/check-i18n.js to validateNever use hardcoded Chinese/English text in JSX:
// Bad
<span>重命名</span>
<span>Delete</span>
{name || '新对话'}
// Good
<span>{t('common.rename')}</span>
<span>{t('common.delete')}</span>
{name || t('conversation.newConversation')}
console.log() / debug output{
"taskCount": "{{count}} task(s)",
"greeting": "Hello, {{name}}!"
}
t('cron.taskCount', { count: 5 });
Use Trans component for complex markup:
import { Trans } from 'react-i18next';
<Trans i18nKey='cron.countdown'>
Task <strong>{{ taskName }}</strong> in <span>{{ countdown }}</span>
</Trans>;
Most terms can be auto-converted from zh-CN, but some need manual review:
| zh-CN | zh-TW | Notes |
|---|---|---|
| 视频 | 影片 | Different term |
| 软件 | 軟體 | Different term |
| 信息 | 訊息 | Different term |
| 默认 | 預設 | Different term |
Before submitting code with new text:
src/common/config/i18n-config.json to get current languages and modulest() functionsupportedLanguagesbun run i18n:types ran first (regenerates i18n-keys.d.ts)node scripts/check-i18n.js passed after types regenerated (no errors)| Mistake | Correct |
|---|---|
| Assuming a fixed number of languages | Always read i18n-config.json first |
| Adding key to only some locales | Add to every locale in supportedLanguages |
Editing i18n-keys.d.ts manually | Run bun run i18n:types to generate |
Using t("New Chat") | Define key: t("conversation.newChat") |
Not updating i18n-config.json for new module | Update config first, then create files |
Adding module JSON but not updating index.ts | Must add import + export in each locale's index.ts |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).