197 lines
4.8 KiB
Markdown
197 lines
4.8 KiB
Markdown
# 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 |