--- name: i18n description: | Internationalization (i18n) workflow and standards for managing translations. Use when: (1) Adding new user-facing text, (2) Creating new components with user-facing text, (3) Reviewing code for i18n compliance, (4) Adding a new translation module. ---

# i18n Skill

Standards and workflow for internationalization. All user-visible text must use i18n.

**Announce at start:** "I'm using i18n skill to ensure proper internationalization."

## IMPORTANT: Read Config First

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.

```bash 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.

## File Structure

``` 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 │ └── ... └── ... ```

### Key Facts

- **Reference language**: defined by `referenceLanguage` in `i18n-config.json` (currently `en-US`) - **Supported languages**: defined by `supportedLanguages` array — read the file to get the current list - **Modules**: defined by `modules` array — read the file to get the current list

## Key Structure

Keys 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**:

```json // common.json — flat keys { "send": "Send", "cancel": "Cancel", "copySuccess": "Copied" }

// cron.json — nested keys { "scheduledTasks": "Scheduled Tasks", "status": { "active": "Active", "paused": "Paused" } } ```

In code:

```typescript t('common.send'); // flat key in common.json t('cron.status.active'); // nested key in cron.json ```

### Key Naming Rules

- Use **camelCase** for key names: `copySuccess`, `scheduledTasks` - Group related keys with nesting: `status.active`, `actions.pause` - Reusable text goes in `common.json`: save, cancel, delete, confirm, etc. - Feature-specific text goes in the corresponding module

### Common Suffixes

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

## Adding New Text — Workflow

### Step 1: Read `src/common/config/i18n-config.json`

Get the current language list and module list. Do not skip this step.

### Step 2: Check Existing Keys

Before adding a new key, search for similar existing keys:

```bash grep -r "keyword" src/renderer/i18n/locales/en-US/ ```

Reuse `common.*` keys when possible.

### Step 3: Choose the Right Module

Match the module to the feature area. If no module fits, consider whether a new module is needed (see "Adding a New Module" below).

### Step 4: Add to ALL Locale Directories

**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` — added - [ ] `zh-TW/<module>.json` — added - [ ] Any other language listed in `src/common/config/i18n-config.json` → `supportedLanguages` — added

A key missing from even one locale will cause `node scripts/check-i18n.js` to fail in CI.

### Step 5: Use in Component

```tsx import { useTranslation } from 'react-i18next';

function MyComponent() { const { t } = useTranslation(); return <button>{t('common.save')}</button>; } ```

### Step 6: Regenerate Types and Validate

Run these two commands **in order** — both must pass before committing:

```bash 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 file - If `check-i18n.js` exits with errors (❌), fix them before proceeding - If `check-i18n.js` exits with warnings only (⚠️), review but may proceed - **Never commit with a stale `i18n-keys.d.ts`**

## Adding a New Module

1. Add module name to `src/common/config/i18n-config.json` → `modules` array 2. Create `<module>.json` in **every** locale directory (read `supportedLanguages` to know which) 3. Add import + export in each locale's `index.ts` 4. Run `bun run i18n:types` to regenerate type definitions 5. Run `node scripts/check-i18n.js` to validate

## Hardcoded String Detection

### Prohibited Patterns

Never use hardcoded Chinese/English text in JSX:

```tsx // Bad <span>重命名</span> <span>Delete</span> {name || '新对话'}

// Good <span>{t('common.rename')}</span> <span>{t('common.delete')}</span> {name || t('conversation.newConversation')} ```

### Exceptions

- Code comments (any language OK) - `console.log()` / debug output - Internal string constants not shown to users

## Interpolation

### Variables

```json { "taskCount": "{{count}} task(s)", "greeting": "Hello, {{name}}!" } ```

```tsx t('cron.taskCount', { count: 5 }); ```

### HTML in Translations

Use Trans component for complex markup:

```tsx import { Trans } from 'react-i18next';

<Trans i18nKey='cron.countdown'> Task <strong>{{ taskName }}</strong> in <span>{{ countdown }}</span> </Trans>; ```

## zh-TW Maintenance

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 |

## Quick Checklist

Before submitting code with new text:

- [ ] Read `src/common/config/i18n-config.json` to get current languages and modules - [ ] All user-visible text uses `t()` function - [ ] New keys added to **every** locale directory in `supportedLanguages` - [ ] No hardcoded Chinese/English in JSX - [ ] zh-TW reviewed for term differences - [ ] `bun run i18n:types` ran first (regenerates `i18n-keys.d.ts`) - [ ] `node scripts/check-i18n.js` passed after types regenerated (no errors)

## Common Mistakes

| 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` |

--- name: i18n description: | Internationalization (i18n) workflow and standards for managing translations. Use when: (1) Adding new user-facing text, (2) Creating new components with user-facing text, (3) Reviewing code for i18n compliance, (4) Adding a new translation module. ---

# i18n Skill

Standards and workflow for internationalization. All user-visible text must use i18n.

**Announce at start:** "I'm using i18n skill to ensure proper internationalization."

## IMPORTANT: Read Config First

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.

```bash 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.

## File Structure

``` 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 │ └── ... └── ... ```

### Key Facts

- **Reference language**: defined by `referenceLanguage` in `i18n-config.json` (currently `en-US`) - **Supported languages**: defined by `supportedLanguages` array — read the file to get the current list - **Modules**: defined by `modules` array — read the file to get the current list

## Key Structure

Keys 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**:

```json // common.json — flat keys { "send": "Send", "cancel": "Cancel", "copySuccess": "Copied" }

// cron.json — nested keys { "scheduledTasks": "Scheduled Tasks", "status": { "active": "Active", "paused": "Paused" } } ```

In code:

```typescript t('common.send'); // flat key in common.json t('cron.status.active'); // nested key in cron.json ```

### Key Naming Rules

- Use **camelCase** for key names: `copySuccess`, `scheduledTasks` - Group related keys with nesting: `status.active`, `actions.pause` - Reusable text goes in `common.json`: save, cancel, delete, confirm, etc. - Feature-specific text goes in the corresponding module

### Common Suffixes

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

## Adding New Text — Workflow

### Step 1: Read `src/common/config/i18n-config.json`

Get the current language list and module list. Do not skip this step.

### Step 2: Check Existing Keys

Before adding a new key, search for similar existing keys:

```bash grep -r "keyword" src/renderer/i18n/locales/en-US/ ```

Reuse `common.*` keys when possible.

### Step 3: Choose the Right Module

Match the module to the feature area. If no module fits, consider whether a new module is needed (see "Adding a New Module" below).

### Step 4: Add to ALL Locale Directories

**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` — added - [ ] `zh-TW/<module>.json` — added - [ ] Any other language listed in `src/common/config/i18n-config.json` → `supportedLanguages` — added

A key missing from even one locale will cause `node scripts/check-i18n.js` to fail in CI.

### Step 5: Use in Component

```tsx import { useTranslation } from 'react-i18next';

function MyComponent() { const { t } = useTranslation(); return <button>{t('common.save')}</button>; } ```

### Step 6: Regenerate Types and Validate

Run these two commands **in order** — both must pass before committing:

```bash 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 file - If `check-i18n.js` exits with errors (❌), fix them before proceeding - If `check-i18n.js` exits with warnings only (⚠️), review but may proceed - **Never commit with a stale `i18n-keys.d.ts`**

## Adding a New Module

1. Add module name to `src/common/config/i18n-config.json` → `modules` array 2. Create `<module>.json` in **every** locale directory (read `supportedLanguages` to know which) 3. Add import + export in each locale's `index.ts` 4. Run `bun run i18n:types` to regenerate type definitions 5. Run `node scripts/check-i18n.js` to validate

## Hardcoded String Detection

### Prohibited Patterns

Never use hardcoded Chinese/English text in JSX:

```tsx // Bad <span>重命名</span> <span>Delete</span> {name || '新对话'}

// Good <span>{t('common.rename')}</span> <span>{t('common.delete')}</span> {name || t('conversation.newConversation')} ```

### Exceptions

- Code comments (any language OK) - `console.log()` / debug output - Internal string constants not shown to users

## Interpolation

### Variables

```json { "taskCount": "{{count}} task(s)", "greeting": "Hello, {{name}}!" } ```

```tsx t('cron.taskCount', { count: 5 }); ```

### HTML in Translations

Use Trans component for complex markup:

```tsx import { Trans } from 'react-i18next';

<Trans i18nKey='cron.countdown'> Task <strong>{{ taskName }}</strong> in <span>{{ countdown }}</span> </Trans>; ```

## zh-TW Maintenance

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 |

## Quick Checklist

Before submitting code with new text:

- [ ] Read `src/common/config/i18n-config.json` to get current languages and modules - [ ] All user-visible text uses `t()` function - [ ] New keys added to **every** locale directory in `supportedLanguages` - [ ] No hardcoded Chinese/English in JSX - [ ] zh-TW reviewed for term differences - [ ] `bun run i18n:types` ran first (regenerates `i18n-keys.d.ts`) - [ ] `node scripts/check-i18n.js` passed after types regenerated (no errors)

## Common Mistakes

| 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` |

--- name: i18n description: | Internationalization (i18n) workflow and standards for managing translations. Use when: (1) Adding new user-facing text, (2) Creating new components with user-facing text, (3) Reviewing code for i18n compliance, (4) Adding a new translation module. ---

# i18n Skill

Standards and workflow for internationalization. All user-visible text must use i18n.

**Announce at start:** "I'm using i18n skill to ensure proper internationalization."

## IMPORTANT: Read Config First

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.

```bash 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.

## File Structure

``` 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 │ └── ... └── ... ```

### Key Facts

- **Reference language**: defined by `referenceLanguage` in `i18n-config.json` (currently `en-US`) - **Supported languages**: defined by `supportedLanguages` array — read the file to get the current list - **Modules**: defined by `modules` array — read the file to get the current list

## Key Structure

Keys 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**:

```json // common.json — flat keys { "send": "Send", "cancel": "Cancel", "copySuccess": "Copied" }

// cron.json — nested keys { "scheduledTasks": "Scheduled Tasks", "status": { "active": "Active", "paused": "Paused" } } ```

In code:

```typescript t('common.send'); // flat key in common.json t('cron.status.active'); // nested key in cron.json ```

### Key Naming Rules

- Use **camelCase** for key names: `copySuccess`, `scheduledTasks` - Group related keys with nesting: `status.active`, `actions.pause` - Reusable text goes in `common.json`: save, cancel, delete, confirm, etc. - Feature-specific text goes in the corresponding module

### Common Suffixes

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

## Adding New Text — Workflow

### Step 1: Read `src/common/config/i18n-config.json`

Get the current language list and module list. Do not skip this step.

### Step 2: Check Existing Keys

Before adding a new key, search for similar existing keys:

```bash grep -r "keyword" src/renderer/i18n/locales/en-US/ ```

Reuse `common.*` keys when possible.

### Step 3: Choose the Right Module

Match the module to the feature area. If no module fits, consider whether a new module is needed (see "Adding a New Module" below).

### Step 4: Add to ALL Locale Directories

**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` — added - [ ] `zh-TW/<module>.json` — added - [ ] Any other language listed in `src/common/config/i18n-config.json` → `supportedLanguages` — added

A key missing from even one locale will cause `node scripts/check-i18n.js` to fail in CI.

### Step 5: Use in Component

```tsx import { useTranslation } from 'react-i18next';

function MyComponent() { const { t } = useTranslation(); return <button>{t('common.save')}</button>; } ```

### Step 6: Regenerate Types and Validate

Run these two commands **in order** — both must pass before committing:

```bash 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 file - If `check-i18n.js` exits with errors (❌), fix them before proceeding - If `check-i18n.js` exits with warnings only (⚠️), review but may proceed - **Never commit with a stale `i18n-keys.d.ts`**

## Adding a New Module

1. Add module name to `src/common/config/i18n-config.json` → `modules` array 2. Create `<module>.json` in **every** locale directory (read `supportedLanguages` to know which) 3. Add import + export in each locale's `index.ts` 4. Run `bun run i18n:types` to regenerate type definitions 5. Run `node scripts/check-i18n.js` to validate

## Hardcoded String Detection

### Prohibited Patterns

Never use hardcoded Chinese/English text in JSX:

```tsx // Bad <span>重命名</span> <span>Delete</span> {name || '新对话'}

// Good <span>{t('common.rename')}</span> <span>{t('common.delete')}</span> {name || t('conversation.newConversation')} ```

### Exceptions

- Code comments (any language OK) - `console.log()` / debug output - Internal string constants not shown to users

## Interpolation

### Variables

```json { "taskCount": "{{count}} task(s)", "greeting": "Hello, {{name}}!" } ```

```tsx t('cron.taskCount', { count: 5 }); ```

### HTML in Translations

Use Trans component for complex markup:

```tsx import { Trans } from 'react-i18next';

<Trans i18nKey='cron.countdown'> Task <strong>{{ taskName }}</strong> in <span>{{ countdown }}</span> </Trans>; ```

## zh-TW Maintenance

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 |

## Quick Checklist

Before submitting code with new text:

- [ ] Read `src/common/config/i18n-config.json` to get current languages and modules - [ ] All user-visible text uses `t()` function - [ ] New keys added to **every** locale directory in `supportedLanguages` - [ ] No hardcoded Chinese/English in JSX - [ ] zh-TW reviewed for term differences - [ ] `bun run i18n:types` ran first (regenerates `i18n-keys.d.ts`) - [ ] `node scripts/check-i18n.js` passed after types regenerated (no errors)

## Common Mistakes

| 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` |

--- name: i18n description: | Internationalization (i18n) workflow and standards for managing translations. Use when: (1) Adding new user-facing text, (2) Creating new components with user-facing text, (3) Reviewing code for i18n compliance, (4) Adding a new translation module. ---

# i18n Skill

Standards and workflow for internationalization. All user-visible text must use i18n.

**Announce at start:** "I'm using i18n skill to ensure proper internationalization."

## IMPORTANT: Read Config First

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.

```bash 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.

## File Structure

``` 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 │ └── ... └── ... ```

### Key Facts

- **Reference language**: defined by `referenceLanguage` in `i18n-config.json` (currently `en-US`) - **Supported languages**: defined by `supportedLanguages` array — read the file to get the current list - **Modules**: defined by `modules` array — read the file to get the current list

## Key Structure

Keys 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**:

```json // common.json — flat keys { "send": "Send", "cancel": "Cancel", "copySuccess": "Copied" }

// cron.json — nested keys { "scheduledTasks": "Scheduled Tasks", "status": { "active": "Active", "paused": "Paused" } } ```

In code:

```typescript t('common.send'); // flat key in common.json t('cron.status.active'); // nested key in cron.json ```

### Key Naming Rules

- Use **camelCase** for key names: `copySuccess`, `scheduledTasks` - Group related keys with nesting: `status.active`, `actions.pause` - Reusable text goes in `common.json`: save, cancel, delete, confirm, etc. - Feature-specific text goes in the corresponding module

### Common Suffixes

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

## Adding New Text — Workflow

### Step 1: Read `src/common/config/i18n-config.json`

Get the current language list and module list. Do not skip this step.

### Step 2: Check Existing Keys

Before adding a new key, search for similar existing keys:

```bash grep -r "keyword" src/renderer/i18n/locales/en-US/ ```

Reuse `common.*` keys when possible.

### Step 3: Choose the Right Module

Match the module to the feature area. If no module fits, consider whether a new module is needed (see "Adding a New Module" below).

### Step 4: Add to ALL Locale Directories

**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` — added - [ ] `zh-TW/<module>.json` — added - [ ] Any other language listed in `src/common/config/i18n-config.json` → `supportedLanguages` — added

A key missing from even one locale will cause `node scripts/check-i18n.js` to fail in CI.

### Step 5: Use in Component

```tsx import { useTranslation } from 'react-i18next';

function MyComponent() { const { t } = useTranslation(); return <button>{t('common.save')}</button>; } ```

### Step 6: Regenerate Types and Validate

Run these two commands **in order** — both must pass before committing:

```bash 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 file - If `check-i18n.js` exits with errors (❌), fix them before proceeding - If `check-i18n.js` exits with warnings only (⚠️), review but may proceed - **Never commit with a stale `i18n-keys.d.ts`**

## Adding a New Module

1. Add module name to `src/common/config/i18n-config.json` → `modules` array 2. Create `<module>.json` in **every** locale directory (read `supportedLanguages` to know which) 3. Add import + export in each locale's `index.ts` 4. Run `bun run i18n:types` to regenerate type definitions 5. Run `node scripts/check-i18n.js` to validate

## Hardcoded String Detection

### Prohibited Patterns

Never use hardcoded Chinese/English text in JSX:

```tsx // Bad <span>重命名</span> <span>Delete</span> {name || '新对话'}

// Good <span>{t('common.rename')}</span> <span>{t('common.delete')}</span> {name || t('conversation.newConversation')} ```

### Exceptions

- Code comments (any language OK) - `console.log()` / debug output - Internal string constants not shown to users

## Interpolation

### Variables

```json { "taskCount": "{{count}} task(s)", "greeting": "Hello, {{name}}!" } ```

```tsx t('cron.taskCount', { count: 5 }); ```

### HTML in Translations

Use Trans component for complex markup:

```tsx import { Trans } from 'react-i18next';

<Trans i18nKey='cron.countdown'> Task <strong>{{ taskName }}</strong> in <span>{{ countdown }}</span> </Trans>; ```

## zh-TW Maintenance

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 |

## Quick Checklist

Before submitting code with new text:

- [ ] Read `src/common/config/i18n-config.json` to get current languages and modules - [ ] All user-visible text uses `t()` function - [ ] New keys added to **every** locale directory in `supportedLanguages` - [ ] No hardcoded Chinese/English in JSX - [ ] zh-TW reviewed for term differences - [ ] `bun run i18n:types` ran first (regenerates `i18n-keys.d.ts`) - [ ] `node scripts/check-i18n.js` passed after types regenerated (no errors)

## Common Mistakes

| 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` |