@neyugn/agent-kits 0.1.0

package/kits/coder/skills/i18n-localization/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: i18n-localization
+description: Internationalization and localization patterns. Use when implementing multi-language support, translation workflows, locale handling, RTL support, or currency/date formatting.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# i18n & Localization Patterns
+
+> Make software work beautifully in every language and culture.
+
+---
+
+## Core Principles
+
+1. **Externalize all strings** - No hardcoded text in components
+2. **Use ICU Message Format** - Handle plurals, gender, and complex formatting
+3. **Design for translation** - Leave room for text expansion (30-50%)
+4. **Test with pseudo-localization** - Catch issues early
+5. **Locale is more than language** - Includes date, number, currency formats
+
+---
+
+## 🔧 Framework Selection
+
+| Framework             | Platform     | Best For                    |
+| --------------------- | ------------ | --------------------------- |
+| **next-intl**         | Next.js      | App Router, RSC support     |
+| **react-intl**        | React        | Established, ICU format     |
+| **i18next**           | Universal    | Flexible, plugin ecosystem  |
+| **vue-i18n**          | Vue          | Vue-native, composition API |
+| **expo-localization** | React Native | Mobile apps with Expo       |
+
+### Decision Tree
+
+```
+Next.js App Router?
+├── Yes → next-intl (best RSC support)
+└── No → React SPA?
+    ├── Yes → react-intl or i18next
+    └── No → Vue?
+        ├── Yes → vue-i18n
+        └── No → i18next (universal)
+```
+
+---
+
+## 📁 Project Structure
+
+```
+locales/
+├── en/
+│   ├── common.json      # Shared strings
+│   ├── auth.json        # Auth-related
+│   ├── dashboard.json   # Feature-specific
+│   └── errors.json      # Error messages
+├── vi/
+│   ├── common.json
+│   ├── auth.json
+│   └── ...
+└── ja/
+    └── ...
+```
+
+### Namespace Strategy
+
+| Namespace   | Contents                    |
+| ----------- | --------------------------- |
+| `common`    | Shared: buttons, labels     |
+| `auth`      | Login, register, password   |
+| `errors`    | Error messages, validations |
+| `[feature]` | Feature-specific strings    |
+
+---
+
+## 🌍 Key Naming Convention
+
+```json
+// ✅ GOOD: Descriptive, hierarchical keys
+{
+  "auth": {
+    "login": {
+      "title": "Sign In",
+      "button": "Sign In",
+      "forgotPassword": "Forgot password?"
+    }
+  }
+}
+
+// ❌ BAD: Flat, unclear keys
+{
+  "login_title": "Sign In",
+  "btn1": "Sign In"
+}
+```
+
+### Naming Rules
+
+| Rule                  | Example                      |
+| --------------------- | ---------------------------- |
+| **camelCase keys**    | `forgotPassword`             |
+| **Nested by feature** | `auth.login.title`           |
+| **Semantic naming**   | `submitButton` not `button1` |
+| **No hardcoded text** | Even for "OK" or "Cancel"    |
+
+---
+
+## 📝 ICU Message Format
+
+### Plurals
+
+```json
+{
+  "itemCount": "{count, plural, =0 {No items} one {# item} other {# items}}"
+}
+```
+
+### Gender/Select
+
+```json
+{
+  "greeting": "{gender, select, male {Mr.} female {Ms.} other {}} {name}"
+}
+```
+
+### Date & Number
+
+```json
+{
+  "lastUpdated": "Updated {date, date, medium}",
+  "price": "Price: {amount, number, ::currency/USD}"
+}
+```
+
+### Rich Text (react-intl)
+
+```tsx
+<FormattedMessage
+  id="terms"
+  defaultMessage="By signing up, you agree to our <link>Terms of Service</link>"
+  values={{
+    link: (chunks) => <Link href="/terms">{chunks}</Link>,
+  }}
+/>
+```
+
+---
+
+## 🔄 Translation Workflow
+
+### Development Flow
+
+```
+1. Add key to en/[namespace].json
+2. Use key in component
+3. Export for translators
+4. Import translations
+5. Review in context
+```
+
+### Translation Management
+
+| Tool         | Pricing     | Best For               |
+| ------------ | ----------- | ---------------------- |
+| **Crowdin**  | Free tier   | Open source, community |
+| **Lokalise** | Paid        | Professional teams     |
+| **Phrase**   | Paid        | Enterprise             |
+| **Tolgee**   | Open source | Self-hosted            |
+
+### Pseudo-localization
+
+```typescript
+// Test without real translations
+// "Hello" → "[Ħëľľö]" (longer + special chars)
+
+const pseudoLocalize = (str: string) => {
+  const map: Record<string, string> = {
+    a: "ä",
+    e: "ë",
+    i: "ï",
+    o: "ö",
+    u: "ü",
+    A: "Ä",
+    E: "Ë",
+    I: "Ï",
+    O: "Ö",
+    U: "Ü",
+  };
+  const converted = str.replace(/[aeiouAEIOU]/g, (c) => map[c] || c);
+  return `[${converted}]`;
+};
+```
+
+---
+
+## 📱 RTL Support
+
+### CSS Approach
+
+```css
+/* Use logical properties */
+.container {
+  /* ❌ Physical */
+  margin-left: 16px;
+  padding-right: 8px;
+
+  /* ✅ Logical (RTL-aware) */
+  margin-inline-start: 16px;
+  padding-inline-end: 8px;
+}
+
+/* Direction-aware flex */
+.row {
+  display: flex;
+  flex-direction: row; /* Auto-reverses in RTL */
+}
+```
+
+### Logical Properties Mapping
+
+| Physical           | Logical               |
+| ------------------ | --------------------- |
+| `left`             | `inline-start`        |
+| `right`            | `inline-end`          |
+| `top`              | `block-start`         |
+| `bottom`           | `block-end`           |
+| `margin-left`      | `margin-inline-start` |
+| `padding-right`    | `padding-inline-end`  |
+| `text-align: left` | `text-align: start`   |
+
+### HTML Direction
+
+```tsx
+<html dir={isRTL ? 'rtl' : 'ltr'} lang={locale}>
+```
+
+---
+
+## 🔢 Formatting
+
+### Dates
+
+```typescript
+// Use Intl.DateTimeFormat
+const formatDate = (date: Date, locale: string) => {
+  return new Intl.DateTimeFormat(locale, {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+  }).format(date);
+};
+
+// Results:
+// en-US: "January 15, 2025"
+// vi-VN: "15 tháng 1, 2025"
+// ja-JP: "2025年1月15日"
+```
+
+### Numbers & Currency
+
+```typescript
+const formatCurrency = (amount: number, locale: string, currency: string) => {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency,
+  }).format(amount);
+};
+
+// Results for 1234.56:
+// en-US, USD: "$1,234.56"
+// vi-VN, VND: "1.234,56 ₫"
+// ja-JP, JPY: "¥1,235" (no decimals)
+```
+
+### Relative Time
+
+```typescript
+const formatRelative = (date: Date, locale: string) => {
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+  const diff = (date.getTime() - Date.now()) / 1000;
+
+  if (Math.abs(diff) < 60) return rtf.format(Math.round(diff), "second");
+  if (Math.abs(diff) < 3600) return rtf.format(Math.round(diff / 60), "minute");
+  // ... etc
+};
+```
+
+---
+
+## ✅ Implementation Checklist
+
+### Setup
+
+- [ ] i18n library installed and configured
+- [ ] Default locale defined
+- [ ] Locale detection (browser/user preference)
+- [ ] Fallback locale strategy
+
+### Content
+
+- [ ] All user-facing strings externalized
+- [ ] ICU format for plurals/formatting
+- [ ] No string concatenation for sentences
+- [ ] Translator context/comments added
+
+### Styling
+
+- [ ] CSS uses logical properties
+- [ ] RTL tested with real RTL content
+- [ ] Text expansion tested (30-50% longer)
+- [ ] Fonts support all target languages
+
+### Testing
+
+- [ ] Pseudo-localization tested
+- [ ] All locales render correctly
+- [ ] Date/number formats verified
+- [ ] RTL layout tested
+
+---
+
+## ❌ Anti-Patterns
+
+| ❌ Don't                          | ✅ Do                                      |
+| --------------------------------- | ------------------------------------------ |
+| Concatenate strings for sentences | Use ICU message format                     |
+| Hardcode "OK", "Cancel", etc.     | Externalize ALL strings                    |
+| Use physical CSS properties       | Use logical properties for RTL             |
+| Assume text length stays same     | Design for 30-50% expansion                |
+| Store locale in localStorage only | Support URL-based locale switching         |
+| Use images with embedded text     | Separate text layer or generate per-locale |
+
+---
+
+## 🔗 Related Skills
+
+| Need           | Skill                    |
+| -------------- | ------------------------ |
+| React patterns | `react-patterns`         |
+| API design     | `api-patterns`           |
+| Accessibility  | `accessibility-patterns` |
+| Testing        | `testing-patterns`       |
+
+---
+
+> **Remember:** Localization is not just translation. It's making users feel the product was made for them, in their language, with their cultural expectations.

package/kits/coder/skills/i18n-localization/scripts/i18n_checker.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""
+i18n Checker - Internationalization audit for AGT-Kit
+======================================================
+
+Detects hardcoded strings and checks translation completeness.
+
+Usage:
+    python3 .agent/skills/i18n-localization/scripts/i18n_checker.py <project_path>
+
+Checks:
+    - Hardcoded strings in JSX/Vue/Python
+    - Locale file completeness (missing keys)
+    - i18n library usage patterns
+"""
+
+import sys
+import re
+import json
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, List, Set, Any
+
+# Fix console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+SKIP_DIRS = {'node_modules', '.git', 'dist', 'build', '__pycache__', '.next', 'venv'}
+
+# Patterns indicating hardcoded strings
+HARDCODED_PATTERNS = {
+    'jsx': [
+        r'>\s*[A-Z][a-zA-Z\s]{3,30}\s*</',  # Text in JSX
+        r'(title|placeholder|label|alt)="[A-Z][a-zA-Z\s]{2,}"',  # Attributes
+    ],
+    'vue': [
+        r'>\s*[A-Z][a-zA-Z\s]{3,30}\s*</',
+        r'(placeholder|label|title)="[A-Z][a-zA-Z\s]{2,}"',
+    ],
+    'python': [
+        r'(print|raise\s+\w+)\s*\(\s*["\'][A-Z][^"\']{5,}["\']',
+        r'flash\s*\(\s*["\'][A-Z][^"\']{5,}["\']',
+    ]
+}
+
+# Patterns indicating proper i18n usage
+I18N_PATTERNS = [
+    r't\(["\']',           # react-i18next
+    r'useTranslation',     # React hook
+    r'\$t\(',              # Vue i18n
+    r'_\(["\']',           # Python gettext
+    r'gettext\(',          # Python
+    r'useTranslations',    # next-intl
+    r'FormattedMessage',   # react-intl
+]
+
+
+def find_locale_files(project_path: Path) -> List[Path]:
+    """Find translation/locale files."""
+    patterns = [
+        '**/locales/**/*.json',
+        '**/translations/**/*.json',
+        '**/lang/**/*.json',
+        '**/i18n/**/*.json',
+        '**/messages/*.json',
+    ]
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            if not any(skip in f.parts for skip in SKIP_DIRS):
+                files.append(f)
+    
+    return files
+
+
+def flatten_keys(d: dict, prefix: str = '') -> Set[str]:
+    """Flatten nested dict keys."""
+    keys = set()
+    for k, v in d.items():
+        new_key = f"{prefix}.{k}" if prefix else k
+        if isinstance(v, dict):
+            keys.update(flatten_keys(v, new_key))
+        else:
+            keys.add(new_key)
+    return keys
+
+
+def check_locale_completeness(locale_files: List[Path]) -> Dict[str, Any]:
+    """Check if all locales have the same keys."""
+    issues = []
+    passed = []
+    
+    if not locale_files:
+        return {'passed': ['No locale files found (not required)'], 'issues': []}
+    
+    # Group by language folder
+    locales: Dict[str, Dict[str, Set[str]]] = {}
+    
+    for f in locale_files:
+        if f.suffix == '.json':
+            try:
+                lang = f.parent.name
+                content = json.loads(f.read_text(encoding='utf-8'))
+                if lang not in locales:
+                    locales[lang] = {}
+                locales[lang][f.stem] = flatten_keys(content)
+            except:
+                continue
+    
+    if len(locales) < 2:
+        passed.append(f"Found {len(locale_files)} locale file(s)")
+        return {'passed': passed, 'issues': issues}
+    
+    passed.append(f"Found {len(locales)} languages: {', '.join(locales.keys())}")
+    
+    # Compare keys across locales
+    all_langs = list(locales.keys())
+    base_lang = all_langs[0]
+    
+    for namespace in locales.get(base_lang, {}):
+        base_keys = locales[base_lang].get(namespace, set())
+        
+        for lang in all_langs[1:]:
+            other_keys = locales.get(lang, {}).get(namespace, set())
+            
+            missing = base_keys - other_keys
+            if missing:
+                issues.append(f"{lang}/{namespace}: Missing {len(missing)} keys")
+            
+            extra = other_keys - base_keys
+            if extra and len(extra) > 3:
+                issues.append(f"{lang}/{namespace}: {len(extra)} extra keys")
+    
+    if not issues:
+        passed.append("All locales have matching keys")
+    
+    return {'passed': passed, 'issues': issues}
+
+
+def check_hardcoded_strings(project_path: Path) -> Dict[str, Any]:
+    """Check for hardcoded strings in code files."""
+    issues = []
+    passed = []
+    
+    extensions = {
+        '.tsx': 'jsx', '.jsx': 'jsx', '.ts': 'jsx', '.js': 'jsx',
+        '.vue': 'vue',
+        '.py': 'python'
+    }
+    
+    code_files = []
+    for ext in extensions:
+        for f in project_path.rglob(f"*{ext}"):
+            if not any(skip in f.parts for skip in SKIP_DIRS):
+                if not any(x in f.name for x in ['test', 'spec', 'config']):
+                    code_files.append(f)
+    
+    if not code_files:
+        return {'passed': ['No code files found'], 'issues': []}
+    
+    files_with_i18n = 0
+    files_with_hardcoded = 0
+    examples = []
+    
+    for file_path in code_files[:50]:  # Limit
+        try:
+            content = file_path.read_text(encoding='utf-8', errors='ignore')
+            ext = file_path.suffix
+            file_type = extensions.get(ext, 'jsx')
+            
+            # Check for i18n usage
+            has_i18n = any(re.search(p, content) for p in I18N_PATTERNS)
+            if has_i18n:
+                files_with_i18n += 1
+            
+            # Check for hardcoded strings
+            patterns = HARDCODED_PATTERNS.get(file_type, [])
+            
+            for pattern in patterns:
+                matches = re.findall(pattern, content)
+                if matches and not has_i18n:
+                    files_with_hardcoded += 1
+                    if len(examples) < 5:
+                        examples.append(f"{file_path.name}: {str(matches[0])[:30]}...")
+                    break
+                    
+        except:
+            continue
+    
+    passed.append(f"Analyzed {len(code_files)} code files")
+    
+    if files_with_i18n > 0:
+        passed.append(f"{files_with_i18n} files use i18n patterns")
+    
+    if files_with_hardcoded > 0:
+        issues.append(f"{files_with_hardcoded} files may have hardcoded strings")
+        for ex in examples[:3]:
+            issues.append(f"  → {ex}")
+    else:
+        passed.append("No obvious hardcoded strings detected")
+    
+    return {'passed': passed, 'issues': issues}
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[AGT-KIT i18n CHECKER] Internationalization Audit")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Check locale files
+    locale_files = find_locale_files(project_path)
+    locale_result = check_locale_completeness(locale_files)
+    
+    # Check hardcoded strings
+    code_result = check_hardcoded_strings(project_path)
+    
+    # Print results
+    print("\n📁 LOCALE FILES")
+    print("-"*40)
+    for item in locale_result['passed']:
+        print(f"  ✅ {item}")
+    for item in locale_result['issues']:
+        print(f"  ⚠️  {item}")
+    
+    print("\n💻 CODE ANALYSIS")
+    print("-"*40)
+    for item in code_result['passed']:
+        print(f"  ✅ {item}")
+    for item in code_result['issues']:
+        print(f"  ⚠️  {item}")
+    
+    # Summary
+    all_issues = locale_result['issues'] + code_result['issues']
+    critical = sum(1 for i in all_issues if 'hardcoded' in i.lower() or 'missing' in i.lower())
+    
+    print("\n" + "="*60)
+    
+    passed = critical == 0
+    
+    if passed:
+        print("✅ i18n CHECK PASSED")
+    else:
+        print(f"⚠️  i18n CHECK: {critical} issues found")
+    
+    output = {
+        "script": "i18n_checker",
+        "skill": "i18n-localization",
+        "project": str(project_path),
+        "locale_files": len(locale_files),
+        "issues": len(all_issues),
+        "passed": passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()