refactor(skill/i18n): improve workflow documentation and scripts

Enhanced documentation and refactored sync/translate scripts for better clarity and maintainability.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ericyangpan

.claude/skills/i18n/SKILL.md

@@ -5,31 +5,57 @@ description: Internationalization management tool for syncing and translating la
 
 # I18n Management Skill
 
-Manage multilingual content in the `locales/` directory. This skill provides tools to synchronize language files with the English reference and assist with translations.
+Manage multilingual content in the `translations/` directory. This skill provides tools to synchronize language files with the English reference and assist with translations.
 
 ## Overview
 
-This project uses `next-intl` for internationalization with JSON message files stored in `locales/`:
+This project uses `next-intl` for internationalization with JSON message files organized in `translations/`:
 
-- `locales/en.json` - English (source of truth)
-- `locales/zh-Hans.json` - Simplified Chinese
-- Additional language files can be added
+```
+translations/
+├── en/                    # English (source of truth)
+│   ├── index.ts           # Main export file
+│   ├── shared.json
+│   ├── components.json
+│   └── pages/
+│       ├── home.json
+│       ├── manifesto.json
+│       ├── docs.json
+│       ├── articles.json
+│       ├── curated-collections.json
+│       ├── stacks.json
+│       └── comparison.json
+├── de/                    # German
+├── zh-Hans/               # Simplified Chinese
+└── ko/                    # Korean
+```
+
+**Important:** Each locale must maintain the exact same file structure and JSON key order as `en/`.
+
+## Enabled Locales
+
+Currently enabled locales in `src/i18n/config.ts`:
+- `en` - English (source of truth)
+- `de` - Deutsch (German)
+- `zh-Hans` - 简体中文 (Simplified Chinese)
+- `ko` - 한국어 (Korean)
 
-All language files must maintain the same nested key structure as `en.json`.
+Additional locale directories may exist but are not enabled in the config.
 
 ## Subcommands
 
 ### `sync`
 
-Synchronize all language files with `en.json` as the source of truth.
+Synchronize all enabled locale directories with `en/` as the source of truth.
 
 **What it does:**
 
-- Scans all `.json` files in `locales/` directory
-- Compares each file's keys with `en.json`
+- Scans all locale directories in `translations/` that are enabled in config
+- Compares each JSON file's keys with the corresponding English file
 - **Adds missing keys** with English text as placeholder (needs translation)
-- **Removes extra keys** not present in `en.json`
-- Preserves JSON structure and formatting (2-space indentation)
+- **Removes extra keys** not present in English files
+- **Preserves JSON structure, key order, and formatting** (2-space indentation)
+- **Keeps the `index.ts` file structure** for each locale
 
 **Usage:**
 
@@ -48,25 +74,30 @@ node .claude/skills/i18n/scripts/sync.mjs
 **Output Example:**
 
 ```
-🔄 Syncing language files with en.json...
+🔄 Syncing translation files with en/...
 
-✓ Synced zh-Hans.json
-  + Added 3 keys
-  - Removed 1 key
+✓ Synced de/
+  + Added 3 keys in components.json
+  + Added 5 keys in pages/home.json
+  - Removed 1 key in shared.json
+
+✓ Synced zh-Hans/
+  + Added 8 keys in pages/stacks.json
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✓ Sync complete!
-  Modified: 1 file
-  Added: 3 keys
+  Modified: 2 locales
+  Added: 16 keys
   Removed: 1 key
 ```
 
 **When to use:**
 
-- After adding new keys to `en.json`
-- After removing obsolete keys from `en.json`
+- After adding new keys to any English JSON file
+- After removing obsolete keys from any English JSON file
+- After adding new JSON files to the English structure
 - Before starting translation work (ensures all keys exist)
-- When adding a new language file
+- When adding a new locale
 
 ---
 
@@ -76,7 +107,7 @@ Generate translation tasks for Claude Code to translate missing content.
 
 **What it does:**
 
-- Reads `en.json` and `<locale>.json`
+- Reads all JSON files from `en/` and `<locale>/`
 - Identifies keys that need translation (currently in English or missing)
 - Outputs a structured translation task with guidelines
 - Provides context and instructions for accurate translation
@@ -100,7 +131,7 @@ node .claude/skills/i18n/scripts/translate.mjs zh-Hans
 1. The script outputs content that needs translation in JSON format
 2. Claude Code reads the guidelines and translates the content
 3. You provide the translated JSON back
-4. Claude Code updates the language file
+4. Claude Code updates the locale JSON files
 
 **Translation Guidelines (automatically enforced):**
 
@@ -109,18 +140,7 @@ node .claude/skills/i18n/scripts/translate.mjs zh-Hans
 ✓ **Don't translate URLs:** `https://example.com`
 ✓ **Don't translate file paths:** `/path/to/file`
 ✓ **Maintain terminology consistency** throughout the translation
-
-**Supported Locales:**
-
-- `zh-Hans` - 简体中文 (Simplified Chinese)
-- `zh-Hant` - 繁體中文 (Traditional Chinese)
-- `ja` - 日本語 (Japanese)
-- `ko` - 한국어 (Korean)
-- `fr` - Français (French)
-- `de` - Deutsch (German)
-- `es` - Español (Spanish)
-- `pt` - Português (Portuguese)
-- `ru` - Русский (Russian)
+✓ **Preserve reference syntax:** `@:path.to.key` for internal references
 
 **Output Example:**
 
@@ -134,17 +154,24 @@ node .claude/skills/i18n/scripts/translate.mjs zh-Hans
 Target Language: 简体中文 (Simplified Chinese)
 Entries to translate: 15
 
+Files affected:
+  - components.json: 5 entries
+  - pages/home.json: 8 entries
+  - shared.json: 2 entries
+
 ⚠ Translation Guidelines:
   1. Preserve brand names: "AI Coding Stack", "Claude Code"
   2. Keep placeholders intact: {count}, {name}, ${variable}
   3. Don't translate URLs and file paths
   4. Maintain consistent terminology
+  5. Preserve reference syntax: @:path.to.key
 
 Content to translate:
 
 {
-  "pages.home.title": "Welcome to AI Coding Stack",
-  "pages.home.description": "Discover the best AI coding tools",
+  "components.languageSwitcher.english": "English",
+  "pages.home.hero.title": "Welcome to AI Coding Stack",
+  "shared.navigation.docs": "Documentation",
   ...
 }
 ```
@@ -168,6 +195,35 @@ Content to translate:
 **JSON Format:** 2-space indentation, trailing newline
 **Encoding:** UTF-8
 
+### Translation File Structure
+
+Each locale has:
+1. **JSON files**: Contain the actual message data
+2. **index.ts**: Imports and assembles messages
+
+```typescript
+// translations/en/index.ts
+import components from './components.json'
+import articles from './pages/articles.json'
+// ... other imports
+
+const messages = {
+  shared,
+  components,
+  pages: {
+    home,
+    manifesto,
+    docs,
+    articles,
+    curatedCollections,
+    ...stacks,
+    comparison,
+  },
+}
+
+export default messages
+```
+
 ### How Keys Are Compared
 
 The scripts use recursive traversal to handle nested JSON structures. Keys are compared using dot notation:
@@ -176,35 +232,54 @@ The scripts use recursive traversal to handle nested JSON structures. Keys are c
 {
   "pages": {
     "home": {
-      "title": "Welcome"
+      "hero": {
+        "title": "Welcome"
+      }
     }
   }
 }
 ```
 
-Becomes: `pages.home.title = "Welcome"`
+Becomes: `pages.home.hero.title = "Welcome"`
 
 ### Adding a New Language
 
 1. Add the locale to `src/i18n/config.ts`:
 
 ```typescript
-export const locales = ['en', 'zh-Hans', 'ja'] as const; // Add 'ja'
+export const locales = ['en', 'de', 'zh-Hans', 'ko', 'ja'] as const; // Add 'ja'
 ```
 
-2. Create an empty JSON file or copy `en.json`:
+2. Update locale names:
+
+```typescript
+export const localeNames: Record<Locale, string> = {
+  // ...
+  ja: '日本語',
+}
+
+export const localeToOgLocale: Record<Locale, string> = {
+  // ...
+  ja: 'ja_JP',
+}
+```
+
+3. Create the locale directory structure:
 
 ```bash
-cp locales/en.json locales/ja.json
+mkdir -p translations/ja/pages
+cp translations/en/index.ts translations/ja/index.ts
+cp translations/en/*.json translations/ja/
+cp translations/en/pages/*.json translations/ja/pages/
 ```
 
-3. Run sync to ensure structure matches:
+4. Run sync to ensure structure matches:
 
 ```
 Please run the i18n sync command
 ```
 
-4. Run translate to generate translation tasks:
+5. Run translate to generate translation tasks:
 
 ```
 Please run the i18n translate command for ja
@@ -213,22 +288,24 @@ Please run the i18n translate command for ja
 ## Best Practices
 
 1. **Always run `sync` before `translate`** to ensure all keys exist
-2. **Make changes to `en.json` first**, then sync other languages
+2. **Make changes to English files first**, then sync other locales
 3. **Review translations** for context accuracy, especially technical terms
 4. **Use Git** to track changes and review diffs before committing
 5. **Keep brand names consistent** across all languages
 6. **Test translations** in the actual UI to verify formatting and length
+7. **Preserve key order** to make diffs easier to review
+8. **Use reference syntax** (`@:path.to.key`) for reused content
 
 ## Troubleshooting
 
-**Problem:** Script says "file not found"
+**Problem:** Script says "directory not found"
 
 - **Solution:** Ensure you're running from project root
-- Check that `locales/` directory exists
+- Check that `translations/` directory exists
 
 **Problem:** Keys are out of sync after adding new content
 
-- **Solution:** Run `sync` command to update all language files
+- **Solution:** Run `sync` command to update all locale files
 
 **Problem:** Translation contains placeholders like `{0}` instead of `{count}`
 
@@ -238,18 +315,21 @@ Please run the i18n translate command for ja
 
 - **Solution:** Run `translate` to find missing translations, check for English fallbacks
 
+**Problem:** index.ts imports are wrong after sync
+
+- **Solution:** The sync script preserves index.ts structure; manually check imports match actual JSON files
+
 ## Integration with next-intl
 
 This skill is designed to work with the project's `next-intl` setup:
 
 ```typescript
 // src/i18n/request.ts
-export default getRequestConfig(async ({ locale }) => ({
-  messages: (await import(`../../locales/${locale}.json`)).default,
-}));
+const rawMessages = (await import(`../../translations/${locale}/index.ts`)).default
+const messages = resolveReferences(rawMessages)
 ```
 
-The JSON files are loaded dynamically based on the current locale.
+The JSON files are loaded through the index.ts for each locale, and the `resolveReferences` function handles `@:path` reference syntax.
 
 ## License