Internationalization guide using react-i18next. Use when adding translations, creating i18n keys, or working with localized text in React components (.tsx files). Triggers on translation tasks, locale management, or i18n implementation.
npxskills add majiayu000/claude-skill-registry--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."
src/renderer/i18n/
├── index.ts # i18next configuration
└── locales/
├── en-US.json # English (primary)
├── zh-CN.json # Simplified Chinese
├── zh-TW.json # Traditional Chinese
├── ja-JP.json # Japanese
└── ko-KR.json # Korean
IMPORTANT: New i18n keys MUST use flat dot-notation format.
Format: <module>.<feature>.<detail>
| Level | Description | Examples |
|---|---|---|
| Module | Page or major feature | cron, chat, settings, auth |
| Feature | Specific functionality | form, list, modal, sidebar |
| Detail | Specific text purpose | title, placeholder, label, empty |
✓ cron.form.title
✓ cron.form.namePlaceholder
✓ cron.list.emptyState
✓ settings.llm.apiKeyRequired
✗ cronFormTitle (missing dots)
✗ CRON.FORM.TITLE (wrong case)
// ✅ GOOD - flat structure (use for NEW keys)
{
"cron.form.title": "Create Scheduled Task",
"cron.form.nameLabel": "Task Name",
"cron.list.empty": "No scheduled tasks"
}
// ❌ AVOID - nested structure (legacy only, do not add new)
{
"cron": {
"form": {
"title": "..."
}
}
}
Rationale:
t('cron.form.title'), search directly)| Suffix | Usage |
|---|---|
title | Section/page titles |
placeholder | Input placeholders |
label | Form labels |
button / action | Button text |
success / error | Status messages |
confirm |
Use common.* for reusable text:
{
"common.save": "Save",
"common.cancel": "Cancel",
"common.confirm": "Confirm",
"common.delete": "Delete",
"common.loading": "Loading..."
}
Before adding new key, search for similar existing keys:
grep -r "keyword" src/renderer/i18n/locales/
CRITICAL: Must add to all 5 files simultaneously.
# Files to update:
src/renderer/i18n/locales/en-US.json # English text
src/renderer/i18n/locales/zh-CN.json # Simplified Chinese
src/renderer/i18n/locales/zh-TW.json # Traditional Chinese
src/renderer/i18n/locales/ja-JP.json # Japanese
src/renderer/i18n/locales/ko-KR.json # Korean
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { t } = useTranslation();
return <button>{t('module.feature.action')}</button>;
}
After adding, verify all files have the new keys.
Always verify key sync across all locale files:
# Quick check - compare line counts (rough indicator)
wc -l src/renderer/i18n/locales/*.json
# Check for flat keys diff between en-US and zh-CN
diff <(grep -oE '"[a-zA-Z0-9_.]+":' src/renderer/i18n/locales/en-US.json | sort -u) \
<(grep -oE '"[a-zA-Z0-9_.]+":' src/renderer/i18n/locales/zh-CN.json | sort -u)
If keys are out of sync:
Never use hardcoded Chinese/English text in JSX:
// ❌ BAD
<span>重命名</span>
<span>Delete</span>
<button title="更多操作">...</button>
{name || '新对话'}
// ✅ GOOD
<span>{t('common.rename')}</span>
<span>{t('common.delete')}</span>
<button title={t('common.moreActions')}>...</button>
{name || t('chat.newConversation')}
Comments and internal logs are allowed:
// This is a comment, Chinese is OK
console.log('Debug info'); // OK for logs
Most terms can be auto-converted from zh-CN:
Some terms need manual review:
| zh-CN | zh-TW | Notes |
|---|---|---|
| 视频 | 影片 | Different term |
| 软件 | 軟體 | Different term |
| 信息 | 訊息 | Different term |
| 默认 | 預設 | Different term |
{
"greeting": "Hello, {{name}}!",
"itemCount": "{{count}} items"
}
t('greeting', { name: 'User' });
t('itemCount', { 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>;
Before submitting code with new text:
t() functionmodule.feature.detail format| Mistake | Correct |
|---|---|
| Adding key to only one file | Add to all 5 files |
| Using nested structure for new | Use flat module.feature.detail |
Using t("New Chat") | Define key: t("chat.new") |
| Inline Chinese in JSX | Use t() with defined key |
| Forgetting interpolation | Use {{variable}} syntax |
| Confirmation dialogs |
empty | Empty state messages |
loading | Loading states |
tooltip | Tooltip text |
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).