Initial commit

2026-03-23 21:37:59 +01:00
commit 2547717edb
2193 changed files with 972171 additions and 0 deletions
--- a/imports/instructions.md
+++ b/imports/instructions.md
@@ -0,0 +1,197 @@
+# 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