# Tag Management Commands - Quick Guide

## Overview
Two Laravel Artisan commands for managing multilingual tags with AI assistance:
- `tags:validate-translations` - Validate and clean existing tags
- `tags:import-export` - Import/export tags, work with AI services

---

## Common Workflow

### 1. Export Categories for AI
```bash
php artisan tags:import-export export-categories
```
→ Creates `exports/categories/categories-for-ai-YYYY-MM-DD-HH-mm-ss.json`

### 2. Request Tags from AI Service
- Send the exported file to ChatGPT, Claude, or similar AI
- Ask: *"Generate 10-15 relevant tags for each category, following the example format"*
- Save AI response as JSON file(s) in `imports/tags/` folder

### 3. Import AI-Generated Tags
```bash
# Preview first
php artisan tags:import-export import --dry-run

# Import all files in imports/tags/
php artisan tags:import-export import
```
→ Processed files move to `imports/tags/processed/`

### 4. Review and Validate
```bash
# Check translation coverage
php artisan tags:validate-translations

# Check specific locale for issues
php artisan tags:validate-translations --locale=nl --show-missing --show-duplicates
```

### 5. Clean Up (if needed)
```bash
# Remove unwanted tag groups
php artisan tags:import-export remove-group

# Remove duplicates (if any)
php artisan tags:validate-translations --locale=nl --show-duplicates
```

---

## Command Reference

### Validation Commands

#### Basic Validation
```bash
php artisan tags:validate-translations
```
Shows translation coverage for all locales (en, nl, fr, es, de)

#### Locale-Specific Analysis
```bash
php artisan tags:validate-translations --locale=nl --show-missing --show-duplicates
```
- `--show-missing`: Lists contexts without Dutch translations
- `--show-duplicates`: Shows duplicate tag names + removal prompt

#### Context Distribution
```bash
php artisan tags:validate-translations --show-contexts
```
Shows top 10 contexts by tag count

### Import/Export Commands

#### Export Categories (for AI)
```bash
php artisan tags:import-export export-categories
```
Creates JSON file with all categories + instructions for AI

#### Import Tags (AI responses)
```bash
# Process all files in imports/tags/
php artisan tags:import-export import

# Process specific file
php artisan tags:import-export import path/to/file.json

# Preview without changes
php artisan tags:import-export import --dry-run
```

#### Export Existing Tags (backup)
```bash
# Export all tags
php artisan tags:import-export export-tags

# Export specific category
php artisan tags:import-export export-tags --category-id=16

# Export specific locale
php artisan tags:import-export export-tags --locale=nl
```

#### Remove Tag Groups
```bash
php artisan tags:import-export remove-group
```
Interactive removal of entire tag groups (all translations)

---

## File Structure

```
project-root/
├── imports/
│   └── tags/              # Drop AI-generated JSON files here
│       └── processed/     # Successfully imported files
└── exports/
    ├── categories/        # Category files for AI input
    └── tags/             # Tag backup exports
```

---

## JSON Format Examples

### Category Export (for AI)
```json
{
  "metadata": {
    "purpose": "AI tag generation input",
    "supported_locales": ["en", "nl", "fr", "es", "de"]
  },
  "categories": [
    {"id": 16, "name": "Education", "slug": "en-education"}
  ],
  "example_format": {
    "tags": [
      {
        "translations": {
          "en": "Math Tutoring",
          "nl": "Wiskunde Bijles",
          "fr": "Cours de Mathématiques",
          "es": "Clases de Matemáticas",
          "de": "Mathe Nachhilfe"
        },
        "category": {"id": 16, "name": "Education"}
      }
    ]
  }
}
```

### AI Response Format (for import)
```json
{
  "tags": [
    {
      "translations": {
        "en": "Science Tutoring",
        "nl": "Wetenschap Bijles",
        "fr": "Cours de Sciences",
        "es": "Clases de Ciencias",
        "de": "Wissenschaft Nachhilfe"
      },
      "category": {"id": 16, "name": "Education"}
    }
  ]
}
```

---

## Key Features

- **One context per tag group** - Each imported tag group gets its own context
- **Max 5 tags per context** - One for each supported language
- **Safe operations** - Transaction-based with rollback on errors
- **Batch processing** - Import multiple AI responses at once
- **Duplicate detection** - Prevents duplicate tag groups and offers cleanup
- **Interactive cleanup** - Guided removal of unwanted tags
- **Comprehensive validation** - Coverage reports and integrity checks

---

## Tips

- Always use `--dry-run` first to preview imports
- Place multiple AI response files in `imports/tags/` for batch processing
- Use validation commands regularly to maintain data quality
- Back up existing tags before major imports: `tags:import-export export-tags`
- Press **Ctrl+C** to abort any command safely