proagents 1.0.0

package/proagents/i18n/README.md

@@ -0,0 +1,133 @@
+# Localization (i18n) Support
+
+Multi-language support for international development teams and applications.
+
+---
+
+## Overview
+
+Integrate localization into your development workflow for seamless multi-language support.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    i18n Workflow                             │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Development                                                │
+│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐    │
+│  │  Code   │──►│ Extract │──►│Translate│──►│ Deploy  │    │
+│  └─────────┘   └─────────┘   └─────────┘   └─────────┘    │
+│       │             │             │             │          │
+│       ▼             ▼             ▼             ▼          │
+│  Use t() keys   Generate     Send to TMS   All languages  │
+│  Mark strings   JSON/YAML    or translate  ready          │
+│                                                             │
+│  Validation: Check coverage, missing keys, plurals        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+### Enable i18n
+
+```yaml
+# proagents.config.yaml
+
+i18n:
+  enabled: true
+  source_language: "en"
+  target_languages: ["es", "fr", "de", "ja", "zh"]
+```
+
+### Extract Strings
+
+```bash
+# Extract translatable strings
+proagents i18n extract
+
+# Check translation coverage
+proagents i18n coverage
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **String Extraction** | Auto-extract translatable strings |
+| **Coverage Reports** | Track translation completion |
+| **Missing Key Detection** | Find untranslated strings |
+| **Plural Validation** | Verify plural forms |
+| **TMS Integration** | Connect to translation services |
+| **CI/CD Checks** | Validate in pipeline |
+
+---
+
+## Documentation Files
+
+| File | Description |
+|------|-------------|
+| [extraction.md](./extraction.md) | String extraction setup |
+| [translation-workflow.md](./translation-workflow.md) | Translation process |
+| [tms-integration.md](./tms-integration.md) | Translation management systems |
+| [validation.md](./validation.md) | Quality checks |
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+
+i18n:
+  enabled: true
+
+  # Languages
+  source_language: "en"
+  target_languages: ["es", "fr", "de", "ja", "zh"]
+
+  # File structure
+  files:
+    format: "json"  # json, yaml, po
+    directory: "src/locales"
+    naming: "{{locale}}/{{namespace}}.json"
+
+  # Extraction
+  extraction:
+    patterns:
+      - "t('...')"
+      - "i18n.t('...')"
+      - "<Trans>...</Trans>"
+    exclude:
+      - "node_modules"
+      - "**/*.test.ts"
+
+  # Validation
+  validation:
+    missing_translations: "warning"
+    unused_keys: "info"
+    placeholder_mismatch: "error"
+
+  # TMS Integration
+  tms:
+    provider: "crowdin"  # crowdin, lokalise, phrase
+    project_id: "my-project"
+    auto_sync: true
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `proagents i18n extract` | Extract strings from code |
+| `proagents i18n coverage` | Show translation coverage |
+| `proagents i18n validate` | Validate translations |
+| `proagents i18n sync` | Sync with TMS |
+| `proagents i18n add-key` | Add new translation key |
+| `proagents i18n missing` | List missing translations |

package/proagents/i18n/extraction.md

@@ -0,0 +1,433 @@
+# String Extraction
+
+Automatically extract translatable strings from your codebase.
+
+---
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Extraction Process                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Source Code                                                │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ const message = t('welcome.title');                 │   │
+│  │ <Trans i18nKey="welcome.subtitle">Welcome!</Trans>  │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                         │                                   │
+│                         ▼                                   │
+│               ┌─────────────────┐                          │
+│               │   Extractor     │                          │
+│               └────────┬────────┘                          │
+│                        │                                    │
+│                        ▼                                    │
+│  Translation Files                                          │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ {                                                   │   │
+│  │   "welcome": {                                      │   │
+│  │     "title": "Welcome",                             │   │
+│  │     "subtitle": "Welcome!"                          │   │
+│  │   }                                                 │   │
+│  │ }                                                   │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Extraction Configuration
+
+### Basic Setup
+
+```yaml
+i18n:
+  extraction:
+    # Patterns to match
+    patterns:
+      # Function calls
+      - pattern: "t\\(['\"](.+?)['\"]"
+        type: "function"
+
+      - pattern: "i18n\\.t\\(['\"](.+?)['\"]"
+        type: "function"
+
+      # React components
+      - pattern: "<Trans\\s+i18nKey=['\"](.+?)['\"]"
+        type: "component"
+
+      - pattern: "<Trans>(.+?)</Trans>"
+        type: "component_content"
+
+    # Files to scan
+    include:
+      - "src/**/*.ts"
+      - "src/**/*.tsx"
+      - "src/**/*.js"
+      - "src/**/*.jsx"
+
+    # Files to exclude
+    exclude:
+      - "**/*.test.*"
+      - "**/*.spec.*"
+      - "**/node_modules/**"
+      - "**/dist/**"
+```
+
+### Advanced Patterns
+
+```yaml
+i18n:
+  extraction:
+    patterns:
+      # With default value
+      - pattern: "t\\(['\"](.+?)['\"],\\s*['\"](.+?)['\"]\\)"
+        type: "function_with_default"
+        key_group: 1
+        default_group: 2
+
+      # With options
+      - pattern: "t\\(['\"](.+?)['\"],\\s*\\{[^}]*\\}\\)"
+        type: "function_with_options"
+
+      # Plurals
+      - pattern: "t\\(['\"](.+?)['\"],\\s*\\{\\s*count:"
+        type: "plural"
+
+      # Template literals
+      - pattern: "t\\(`(.+?)`\\)"
+        type: "template_literal"
+        warning: "Dynamic keys cannot be extracted"
+```
+
+---
+
+## Running Extraction
+
+### Basic Extraction
+
+```bash
+# Extract all strings
+proagents i18n extract
+
+# Extract to specific directory
+proagents i18n extract --output src/locales
+
+# Dry run (preview only)
+proagents i18n extract --dry-run
+```
+
+### Extraction Options
+
+```bash
+# Extract with specific format
+proagents i18n extract --format json
+
+# Extract only new keys
+proagents i18n extract --new-only
+
+# Extract with context
+proagents i18n extract --include-context
+
+# Extract to specific namespace
+proagents i18n extract --namespace common
+```
+
+### Output
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ String Extraction Results                                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Files Scanned: 145                                          │
+│ Strings Extracted: 342                                      │
+│                                                             │
+│ New Keys: 12                                                │
+│ ├── common.save                                            │
+│ ├── common.cancel                                          │
+│ ├── auth.login_button                                      │
+│ └── ... 9 more                                             │
+│                                                             │
+│ Warnings: 3                                                 │
+│ ├── src/utils/format.ts:15 - Dynamic key detected          │
+│ ├── src/components/Menu.tsx:42 - Missing default value     │
+│ └── src/pages/Home.tsx:78 - Duplicate key                  │
+│                                                             │
+│ Output: src/locales/en/extracted.json                      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Naming
+
+### Naming Convention
+
+```yaml
+i18n:
+  key_naming:
+    # Convention
+    style: "dot_notation"  # dot_notation, snake_case, camelCase
+
+    # Auto-generate key from content
+    auto_generate:
+      enabled: true
+      max_length: 40
+      hash_suffix: false
+
+    # Namespace from file path
+    namespace_from_path:
+      enabled: true
+      base_path: "src"
+      mapping:
+        "components": "common"
+        "pages": "pages"
+        "features": "features"
+```
+
+### Examples
+
+```typescript
+// File: src/components/Button.tsx
+t('common.button.submit')  // Namespace: common
+
+// File: src/pages/Login.tsx
+t('pages.login.title')     // Namespace: pages
+
+// File: src/features/checkout/Cart.tsx
+t('features.checkout.cart.empty')  // Namespace: features
+```
+
+---
+
+## Default Values
+
+### Extract with Defaults
+
+```yaml
+i18n:
+  extraction:
+    default_values:
+      enabled: true
+      source: "code"  # code, comment, second_argument
+
+      # From code content
+      patterns:
+        - "<Trans>(.+?)</Trans>"
+
+      # From comments
+      comment_pattern: "// i18n: (.+)"
+```
+
+### In Code
+
+```typescript
+// Default from second argument
+t('welcome.title', 'Welcome to our app')
+
+// Default from component content
+<Trans i18nKey="welcome.subtitle">
+  Welcome to our amazing application!
+</Trans>
+
+// Default from comment
+// i18n: Click here to continue
+t('common.continue')
+```
+
+---
+
+## Namespace Management
+
+### Multiple Namespaces
+
+```yaml
+i18n:
+  namespaces:
+    # Define namespaces
+    list:
+      - name: "common"
+        description: "Shared UI strings"
+        files: "src/components/**"
+
+      - name: "pages"
+        description: "Page-specific strings"
+        files: "src/pages/**"
+
+      - name: "errors"
+        description: "Error messages"
+        files: "src/errors/**"
+
+      - name: "validation"
+        description: "Form validation"
+        files: "src/validation/**"
+```
+
+### Output Structure
+
+```
+src/locales/
+├── en/
+│   ├── common.json
+│   ├── pages.json
+│   ├── errors.json
+│   └── validation.json
+├── es/
+│   ├── common.json
+│   └── ...
+└── fr/
+    └── ...
+```
+
+---
+
+## Incremental Extraction
+
+### Track Changes
+
+```yaml
+i18n:
+  extraction:
+    incremental:
+      enabled: true
+      tracking_file: ".proagents/i18n-state.json"
+
+      # Only extract from changed files
+      changed_files_only: true
+
+      # Add new keys without removing old
+      merge_strategy: "add_only"
+
+      # Remove unused keys
+      remove_unused:
+        enabled: false
+        after_days: 30
+```
+
+### Commands
+
+```bash
+# Extract only from changed files
+proagents i18n extract --incremental
+
+# Extract and remove unused
+proagents i18n extract --prune-unused
+
+# Full re-extraction
+proagents i18n extract --full
+```
+
+---
+
+## Context and Comments
+
+### Add Context for Translators
+
+```typescript
+// Add context as comment
+// i18n-context: Button shown after successful payment
+t('checkout.success_button')
+
+// Or in options
+t('checkout.success_button', {
+  context: 'Button shown after successful payment'
+})
+```
+
+### Extract Context
+
+```yaml
+i18n:
+  extraction:
+    context:
+      enabled: true
+      sources:
+        - "comment"  # // i18n-context: ...
+        - "option"   # t('key', { context: '...' })
+        - "jsdoc"    # /** @i18n-context ... */
+
+      output:
+        include_in_json: true
+        separate_file: false
+```
+
+### Output with Context
+
+```json
+{
+  "checkout": {
+    "success_button": {
+      "value": "Continue Shopping",
+      "context": "Button shown after successful payment",
+      "source": "src/pages/Checkout.tsx:145"
+    }
+  }
+}
+```
+
+---
+
+## Validation During Extraction
+
+### Validate Keys
+
+```yaml
+i18n:
+  extraction:
+    validation:
+      # Check for duplicate keys
+      duplicates: "error"
+
+      # Check for invalid characters
+      invalid_chars: "error"
+
+      # Check key length
+      max_key_length: 100
+
+      # Check for dynamic keys
+      dynamic_keys: "warning"
+
+      # Check for missing defaults
+      missing_defaults: "warning"
+```
+
+### Validation Output
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Extraction Validation                                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Errors (2):                                                 │
+│ ├── src/components/Menu.tsx:42                             │
+│ │   Duplicate key: 'common.menu.home'                      │
+│ │   First occurrence: src/components/Header.tsx:15         │
+│ │                                                           │
+│ └── src/pages/Settings.tsx:78                              │
+│     Invalid characters in key: 'settings.user name'        │
+│     Suggestion: 'settings.user_name'                       │
+│                                                             │
+│ Warnings (3):                                               │
+│ ├── Dynamic key detected (cannot extract)                  │
+│ └── Missing default value (2 occurrences)                  │
+│                                                             │
+│ Extraction blocked due to errors. Fix and retry.           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Best Practices
+
+1. **Consistent Naming**: Use a consistent key naming convention
+2. **Provide Defaults**: Always include default English text
+3. **Add Context**: Help translators understand usage
+4. **Use Namespaces**: Organize keys by feature/page
+5. **Avoid Dynamic Keys**: Extract only static keys
+6. **Run Regularly**: Extract as part of development workflow
+7. **Review Changes**: Check extracted keys before sending for translation