@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/skills/i18n-nextintl/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: i18n-nextintl
+description: |
+  Internationalization with next-intl for Next.js 15.
+  Supports core/theme/entity message layers, namespace groups, and translation registry.
+  Use this skill when adding translations, validating i18n, or working with localized content.
+allowed-tools: Read, Glob, Grep, Bash(python:*)
+version: 1.0.0
+---
+
+# i18n with next-intl Skill
+
+Internationalization patterns for Next.js 15 using next-intl with auto-generated translation registry.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    TRANSLATION SOURCES                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. CORE MESSAGES (Application-wide)                            │
+│     core/messages/{locale}/                                     │
+│     ├── index.ts          # Re-exports all namespaces           │
+│     ├── common.json       # Buttons, labels, etc.               │
+│     ├── auth.json         # Authentication messages             │
+│     ├── dashboard.json    # Dashboard UI                        │
+│     └── ...                                                     │
+│                                                                 │
+│  2. THEME MESSAGES (Theme-specific overrides)                   │
+│     contents/themes/{theme}/messages/{locale}.json              │
+│     - Extends/overrides core translations                       │
+│     - Custom roles (editor, moderator) ONLY here                │
+│                                                                 │
+│  3. ENTITY MESSAGES (Entity-specific)                           │
+│     contents/themes/{theme}/entities/{entity}/messages/         │
+│     - Field labels, placeholders, descriptions                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## When to Use This Skill
+
+- Adding new translations to components
+- Validating translation completeness (EN/ES)
+- Finding hardcoded strings in UI
+- Understanding namespace structure
+- Working with custom team roles (theme-level only)
+
+## Supported Locales
+
+- `en` - English (default)
+- `es` - Spanish
+
+## Key Concepts
+
+### Namespace Groups
+
+The system uses optimized namespace loading based on page context:
+
+```typescript
+const NAMESPACE_GROUPS = {
+  // Public pages (includes auth for login/signup buttons)
+  PUBLIC_INITIAL: ['common', 'public', 'auth'],
+
+  // Dashboard (authenticated users)
+  DASHBOARD_AUTHENTICATED: ['common', 'dashboard', 'settings', 'public', 'teams'],
+
+  // Auth-specific pages
+  AUTH_ONLY: ['common', 'auth', 'validation'],
+
+  // Fallback (all namespaces)
+  ALL: ['common', 'dashboard', 'settings', 'auth', 'public', 'validation', 'teams']
+}
+```
+
+### Translation Registry
+
+Auto-generated at `core/lib/registries/translation-registry.ts`:
+
+```typescript
+// ✅ CORRECT - Use registry functions
+import { loadThemeTranslation } from '@/core/lib/registries/translation-registry'
+
+const translations = await loadThemeTranslation(themeName, locale)
+
+// ❌ NEVER - Runtime string interpolation
+const translations = await import(`@/contents/themes/${theme}/messages/${locale}.json`)
+```
+
+## Component Patterns
+
+### Server Components
+
+```typescript
+import { getTranslations } from 'next-intl/server'
+
+export default async function WelcomePage() {
+  const t = await getTranslations('welcome')
+
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      <p>{t('description')}</p>
+    </div>
+  )
+}
+```
+
+### Client Components
+
+```typescript
+'use client'
+import { useTranslations } from 'next-intl'
+
+export function WelcomeCard() {
+  const t = useTranslations('welcome')
+
+  return (
+    <div>
+      <h2>{t('title')}</h2>
+      <p>{t('description')}</p>
+    </div>
+  )
+}
+```
+
+### With Dynamic Values
+
+```typescript
+// Translation file
+{
+  "welcome": {
+    "greeting": "Hello, {name}!",
+    "items": "{count, plural, =0 {No items} =1 {One item} other {# items}}"
+  }
+}
+
+// Component
+const t = useTranslations('welcome')
+<p>{t('greeting', { name: user.name })}</p>
+<p>{t('items', { count: items.length })}</p>
+```
+
+## Custom Roles Rule (CRITICAL)
+
+**Custom role translations MUST NEVER be in core/messages/. They belong ONLY in theme messages.**
+
+| Translation Key | Core (`core/messages/`) | Theme (`contents/themes/*/messages/`) |
+|-----------------|-------------------------|---------------------------------------|
+| `teams.roles.owner` | MUST define here | Can override |
+| `teams.roles.admin` | MUST define here | Can override |
+| `teams.roles.member` | MUST define here | Can override |
+| `teams.roles.viewer` | MUST define here | Can override |
+| `teams.roles.editor` | MUST NOT define | MUST define here |
+| `teams.roles.moderator` | MUST NOT define | MUST define here |
+
+### Correct Pattern
+
+```json
+// core/messages/en/teams.json - ONLY core roles
+{
+  "teams": {
+    "roles": {
+      "owner": "Owner",
+      "admin": "Administrator",
+      "member": "Member",
+      "viewer": "Viewer"
+    }
+  }
+}
+
+// contents/themes/default/messages/en.json - Theme extends
+{
+  "teams": {
+    "roles": {
+      "editor": "Editor",
+      "moderator": "Moderator"
+    }
+  }
+}
+```
+
+## Translation Key Naming
+
+```typescript
+// ✅ CORRECT - Hierarchical, descriptive
+{
+  "auth": {
+    "login": {
+      "title": "Sign In",
+      "emailLabel": "Email Address",
+      "errors": {
+        "invalidCredentials": "Invalid email or password"
+      }
+    }
+  }
+}
+
+// ❌ FORBIDDEN - Flat, unclear keys
+{
+  "login_title": "Sign In",
+  "email": "Email"
+}
+```
+
+## Scripts
+
+### Find Hardcoded Strings
+```bash
+# Find hardcoded strings in components
+python .claude/skills/i18n-nextintl/scripts/extract-hardcoded.py \
+  --path contents/themes/default/components/
+
+# Preview without file details
+python .claude/skills/i18n-nextintl/scripts/extract-hardcoded.py \
+  --path app/ \
+  --dry-run
+```
+
+### Validate Translation Completeness
+```bash
+# Compare EN and ES translations
+python .claude/skills/i18n-nextintl/scripts/validate-translations.py
+
+# Check theme-specific translations
+python .claude/skills/i18n-nextintl/scripts/validate-translations.py \
+  --theme default
+
+# Strict mode (exit with error if missing keys)
+python .claude/skills/i18n-nextintl/scripts/validate-translations.py \
+  --strict
+```
+
+### Add Translation Key
+```bash
+# Add key to both locales
+python .claude/skills/i18n-nextintl/scripts/add-translation.py \
+  --key "settings.profile.title" \
+  --en "Profile Settings" \
+  --es "Configuracion de Perfil"
+
+# Add to theme messages instead of core
+python .claude/skills/i18n-nextintl/scripts/add-translation.py \
+  --key "teams.roles.editor" \
+  --en "Editor" \
+  --es "Editor" \
+  --theme default
+
+# Preview without writing
+python .claude/skills/i18n-nextintl/scripts/add-translation.py \
+  --key "new.key" \
+  --en "Value" \
+  --es "Valor" \
+  --dry-run
+```
+
+## Anti-Patterns
+
+```typescript
+// ❌ NEVER: Hardcoded user-facing text
+export function WelcomeCard() {
+  return <h1>Welcome to Dashboard</h1>  // Wrong!
+}
+
+// ❌ NEVER: String concatenation
+const message = "Welcome, " + userName + "!"
+
+// ❌ NEVER: Runtime string interpolation in imports
+const translations = await import(`@/core/messages/${locale}/`)
+
+// ✅ CORRECT: Use translations
+export function WelcomeCard() {
+  const t = useTranslations('dashboard')
+  return <h1>{t('welcome')}</h1>
+}
+
+// ✅ CORRECT: Use interpolation
+const message = t('greeting', { name: userName })
+```
+
+## File Locations
+
+| Type | Location | Who Modifies |
+|------|----------|--------------|
+| Core translations | `core/messages/{locale}/` | Core maintainers |
+| Theme translations | `contents/themes/{theme}/messages/{locale}.json` | Theme developers |
+| Entity translations | Entity config `i18n.loaders` | Entity developers |
+| Translation registry | `core/lib/registries/translation-registry.ts` | Auto-generated |
+| i18n config | `core/i18n.ts` | Core maintainers |
+
+## Checklist
+
+Before committing i18n changes:
+
+- [ ] All user-facing text uses translation keys (no hardcoded strings)
+- [ ] Translation keys exist in ALL supported locales (en, es)
+- [ ] Translation keys follow hierarchical naming convention
+- [ ] Pluralization uses ICU message format
+- [ ] Dynamic values use translation interpolation (no concatenation)
+- [ ] Custom roles defined ONLY in theme messages (never core)
+- [ ] No runtime string interpolation in dynamic imports

package/claude/skills/i18n-nextintl/scripts/add-translation.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+Add Translation Script
+
+Adds a translation key to both EN and ES locales.
+Supports both core messages and theme messages.
+
+Usage:
+    python add-translation.py --key KEY --en VALUE --es VALUE [--theme THEME]
+
+Options:
+    --key KEY       Dot-notation key (e.g., "settings.profile.title")
+    --en VALUE      English translation value
+    --es VALUE      Spanish translation value
+    --theme THEME   Add to theme messages instead of core
+    --namespace NS  Core namespace file (e.g., "dashboard", "common")
+    --dry-run       Preview without writing files
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, Any
+
+
+def get_active_theme() -> str:
+    """Get active theme from environment or default."""
+    return os.environ.get('NEXT_PUBLIC_ACTIVE_THEME', 'default')
+
+
+def load_json_file(file_path: Path) -> dict:
+    """Load JSON file and return dict."""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return {}
+    except json.JSONDecodeError as e:
+        print(f"  Error: Invalid JSON in {file_path}: {e}")
+        sys.exit(1)
+
+
+def save_json_file(file_path: Path, data: dict, dry_run: bool = False) -> None:
+    """Save dict to JSON file with proper formatting."""
+    if dry_run:
+        print(f"  Would write to: {file_path}")
+        return
+
+    # Ensure parent directory exists
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(file_path, 'w', encoding='utf-8') as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write('\n')  # Add trailing newline
+
+
+def set_nested_value(data: dict, key_path: str, value: Any) -> dict:
+    """Set a value in a nested dict using dot notation."""
+    keys = key_path.split('.')
+    current = data
+
+    # Navigate to the parent of the target key
+    for key in keys[:-1]:
+        if key not in current:
+            current[key] = {}
+        elif not isinstance(current[key], dict):
+            # Key exists but is not a dict, cannot proceed
+            raise ValueError(f"Cannot set '{key_path}': '{key}' is not an object")
+        current = current[key]
+
+    # Set the final value
+    current[keys[-1]] = value
+    return data
+
+
+def get_nested_value(data: dict, key_path: str) -> Any:
+    """Get a value from a nested dict using dot notation."""
+    keys = key_path.split('.')
+    current = data
+
+    for key in keys:
+        if not isinstance(current, dict) or key not in current:
+            return None
+        current = current[key]
+
+    return current
+
+
+def infer_namespace(key: str) -> str:
+    """Infer namespace from key path."""
+    # First part of key is typically the namespace
+    parts = key.split('.')
+    if len(parts) >= 1:
+        return parts[0]
+    return 'common'
+
+
+def add_to_core(key: str, en_value: str, es_value: str, namespace: str, dry_run: bool) -> bool:
+    """Add translation to core messages."""
+    # Determine file paths
+    en_path = Path(f'core/messages/en/{namespace}.json')
+    es_path = Path(f'core/messages/es/{namespace}.json')
+
+    # Load existing data
+    en_data = load_json_file(en_path)
+    es_data = load_json_file(es_path)
+
+    # Remove namespace prefix from key if it matches
+    key_without_ns = key
+    if key.startswith(f'{namespace}.'):
+        key_without_ns = key[len(namespace) + 1:]
+
+    # Check if key already exists
+    if get_nested_value(en_data, key_without_ns) is not None:
+        print(f"  Warning: Key '{key}' already exists in EN")
+
+    # Set values
+    en_data = set_nested_value(en_data, key_without_ns, en_value)
+    es_data = set_nested_value(es_data, key_without_ns, es_value)
+
+    # Save files
+    save_json_file(en_path, en_data, dry_run)
+    save_json_file(es_path, es_data, dry_run)
+
+    return True
+
+
+def add_to_theme(key: str, en_value: str, es_value: str, theme: str, dry_run: bool) -> bool:
+    """Add translation to theme messages."""
+    en_path = Path(f'contents/themes/{theme}/messages/en.json')
+    es_path = Path(f'contents/themes/{theme}/messages/es.json')
+
+    # Check if theme exists
+    theme_path = Path(f'contents/themes/{theme}')
+    if not theme_path.exists():
+        print(f"  Error: Theme '{theme}' not found at {theme_path}")
+        return False
+
+    # Load existing data
+    en_data = load_json_file(en_path)
+    es_data = load_json_file(es_path)
+
+    # Check if key already exists
+    if get_nested_value(en_data, key) is not None:
+        print(f"  Warning: Key '{key}' already exists in EN")
+
+    # Set values
+    en_data = set_nested_value(en_data, key, en_value)
+    es_data = set_nested_value(es_data, key, es_value)
+
+    # Save files
+    save_json_file(en_path, en_data, dry_run)
+    save_json_file(es_path, es_data, dry_run)
+
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Add translation key')
+    parser.add_argument('--key', required=True, help='Dot-notation key path')
+    parser.add_argument('--en', required=True, help='English value')
+    parser.add_argument('--es', required=True, help='Spanish value')
+    parser.add_argument('--theme', default=None, help='Add to theme instead of core')
+    parser.add_argument('--namespace', default=None, help='Core namespace file')
+    parser.add_argument('--dry-run', action='store_true', help='Preview without writing')
+
+    args = parser.parse_args()
+
+    print(f"\n{'=' * 60}")
+    print(f"ADDING TRANSLATION")
+    print(f"{'=' * 60}")
+    print(f"Key: {args.key}")
+    print(f"EN: {args.en}")
+    print(f"ES: {args.es}")
+
+    if args.theme:
+        print(f"Target: Theme ({args.theme})")
+    else:
+        namespace = args.namespace or infer_namespace(args.key)
+        print(f"Target: Core (namespace: {namespace})")
+
+    print(f"Dry run: {args.dry_run}")
+    print(f"{'=' * 60}\n")
+
+    try:
+        if args.theme:
+            # Add to theme messages
+            success = add_to_theme(args.key, args.en, args.es, args.theme, args.dry_run)
+        else:
+            # Add to core messages
+            namespace = args.namespace or infer_namespace(args.key)
+            success = add_to_core(args.key, args.en, args.es, namespace, args.dry_run)
+
+        if success:
+            if args.dry_run:
+                print("  DRY RUN: No files were modified")
+            else:
+                print("  Translation added successfully!")
+
+            print(f"\n{'=' * 60}")
+            print("USAGE IN COMPONENT:")
+            print("=" * 60)
+
+            # Show usage example
+            namespace = args.namespace or infer_namespace(args.key)
+            key_parts = args.key.split('.')
+            if len(key_parts) > 1:
+                t_namespace = key_parts[0]
+                t_key = '.'.join(key_parts[1:])
+            else:
+                t_namespace = namespace
+                t_key = args.key
+
+            print(f"""
+  // Client component
+  import {{ useTranslations }} from 'next-intl'
+
+  const t = useTranslations('{t_namespace}')
+  <span>{{t('{t_key}')}}</span>
+
+  // Server component
+  import {{ getTranslations }} from 'next-intl/server'
+
+  const t = await getTranslations('{t_namespace}')
+  <span>{{t('{t_key}')}}</span>
+""")
+            print("=" * 60 + "\n")
+            return 0
+        else:
+            return 1
+
+    except ValueError as e:
+        print(f"  Error: {e}")
+        return 1
+    except Exception as e:
+        print(f"  Unexpected error: {e}")
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())