home / skills / project-n-e-k-o / n.e.k.o / i18n

i18n skill

This skill helps you detect and fix hardcoded Chinese text and synchronize translations across languages in i18n projects.

npx playbooks add skill project-n-e-k-o/n.e.k.o --skill i18n

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.3 KB

---
name: i18n
description: "i18n (internationalization) toolkit for projects using i18next. Provides three main functions: (1) i18n-check - Detect hardcoded Chinese text in HTML/JS files, (2) i18n-fix - Replace hardcoded text with i18n markers, (3) i18n-sync - Align translation keys across multiple languages (zh-CN, en, ja, ko, zh-TW). Use when working on internationalization tasks, detecting untranslated strings, or syncing locale files."
---

# i18n Toolkit

Complete i18n (internationalization) toolkit for projects using i18next.

## Architecture

- **i18n library**: i18next
- **Locale files**: `static/locales/` (zh-CN, zh-TW, en, ja, ko)
- **HTML attributes**: `data-i18n`, `data-i18n-placeholder`, `data-i18n-title`, `data-i18n-alt`
- **JS function**: `window.t()` or `i18next.t()`
- **Progress file**: `.claude/i18n-progress.json`

## Three Main Commands

### 1. i18n-check - Detect Issues

Check frontend files for hardcoded Chinese text.

```
/i18n-check <module> [options]
```

**Modules**: main, live2d, voice, steam, settings, chat, custom

**Options**: `--status`, `--reset`, `--files=<path>`, `--html`, `--js`, `--strict`

See [references/check-modules.md](references/check-modules.md) for module file mappings.

### 2. i18n-fix - Fix Issues

Replace hardcoded Chinese with i18n markers.

```
/i18n-fix <module> [--add-keys]
```

**Fix patterns**:
- HTML: Add `data-i18n="key"` attributes
- JS: Use `window.t('key')` with fallback

See [references/fix-patterns.md](references/fix-patterns.md) for examples.

### 3. i18n-sync - Sync Languages

Align translation keys across all languages.

```bash
python3 scripts/i18n_sync.py          # Check status
python3 scripts/i18n_sync.py --apply  # Apply changes
```

## Quick Workflow

1. **Check**: `/i18n-check steam` - Find hardcoded strings
2. **Fix**: `/i18n-fix steam` - Replace with i18n markers
3. **Verify**: `/i18n-check steam` - Confirm fixes
4. **Sync**: `/i18n-sync` - Sync to other languages

## Detection Rules

### Check for:
- HTML: Chinese text in elements or attributes
- JS: Chinese strings not wrapped in `window.t()`

### Skip:
- Already has `data-i18n*` or `window.t()` wrapper
- `console.log/error/warn` debug messages
- Third-party libs (`static/libs/`)
- Comments
- Internal logic strings (e.g., `includes('已离开')`)
- Data keys (e.g., `data['档案名']`)

Overview

This skill is an i18n (internationalization) toolkit tailored for projects using i18next. It helps detect hardcoded Chinese text, replace it with i18n markers, and synchronize translation keys across zh-CN, en, ja, ko, and zh-TW locale files. Use it to speed up localization audits and keep locale files consistent across languages.

How this skill works

The toolkit offers three commands: i18n-check scans HTML and JS files for hardcoded Chinese text using rules that ignore already localized attributes and known skips. i18n-fix inserts data-i18n attributes in HTML or wraps JS strings with window.t('key') and optional fallbacks. i18n-sync compares locale folders and aligns keys, reporting missing or extra entries and optionally applying changes.

When to use it

When auditing a frontend for untranslated Chinese strings
Before releasing a build that must support multiple locales
After adding new UI copy to ensure keys are created consistently
When keeping locale files synchronized across zh-CN, en, ja, ko, zh-TW
During automated QA to detect regressions in internationalization

Best practices

Run i18n-check per module to focus scans and reduce noise (modules: main, live2d, voice, steam, settings, chat, custom)
Use i18n-fix with a review step — auto-inserted keys often need human-friendly key naming and context
Keep translation source (zh-CN) authoritative and run i18n-sync regularly to propagate structure to other locales
Exclude third-party libs and debug logs from scans to avoid false positives
Keep a progress file to track work in flight and avoid duplicated fixes (.claude/i18n-progress.json)

Example use cases

Scan the steam module before a feature freeze to find hardcoded Chinese strings
Automatically replace visible copy with data-i18n attributes in HTML for a UI refactor
Wrap JS literals in window.t() during a code cleanup to enable runtime translation
Run i18n-sync to detect missing translation keys after adding new UI labels
Integrate i18n-check into pre-commit or CI to block unchecked Chinese text

FAQ

Which file types and attributes are inspected?

HTML elements and attributes (data-i18n*, title, placeholder, alt) and JS files for string literals not wrapped in window.t() or i18next.t().

How do I avoid false positives?

The tool skips files in static/libs, ignores strings already using data-i18n or window.t(), and omits console/debug messages, comments, and known internal data-key patterns.

Can i18n-sync modify files automatically?

Yes — i18n-sync can only report or apply changes. Run the check first, then use the --apply option to update locale files.