timebank-cc-public/imports/instructions.md

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

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

# 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

# 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)

# 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

php artisan tags:validate-translations

Shows translation coverage for all locales (en, nl, fr, es, de)

Locale-Specific Analysis

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

php artisan tags:validate-translations --show-contexts

Shows top 10 contexts by tag count

Import/Export Commands

Export Categories (for AI)

php artisan tags:import-export export-categories

Creates JSON file with all categories + instructions for AI

Import Tags (AI responses)

# 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)

# 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

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)

{
  "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)

{
  "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