@akson/cortex-shopify-translations/translations/scripts/README.md

Unified Shopify translations management client with product extraction, translation sync, and CLI tools

# 🧠 MyArmy Translation Scripts

AI-powered translation system for MyArmy.ch Shopify store.

## Quick Start

```bash
# Check translation status
node translations/scripts/get-status.mjs

# Translate all pending (processes in batches)
node translations/scripts/translate-file.mjs

# Translate specific category
node translations/scripts/translate-file.mjs --category=myarmy

# Translate specific language only
node translations/scripts/translate-file.mjs --lang=de
```

## Scripts Overview

### Core Translation
- **translate-file.mjs** - Main AI translation script
- **ai-translator.mjs** - OpenAI GPT-4o-mini engine

### Status Management
- **get-status.mjs** - Check progress across all files
- **reset-failed.mjs** - Reset failed translations to pending
- **mark-reviewed.mjs** - Mark quality translations as reviewed

### Utilities
- **search-translations.mjs** - Find specific translations
- **validate-translations.mjs** - Check translation quality
- **merge-back.mjs** - Combine for Shopify publish

### Setup
- **split-translations.mjs** - Split large file into categories

## File Structure

```
translations/
├── config/
│   ├── .env              # OPENAI_API_KEY
│   ├── glossary.json     # 400+ military terms
│   └── brand.json        # Voice & guidelines
├── content/
│   ├── checkout.json     # 2,965 translations
│   ├── customer.json     # 403 translations
│   ├── products.json     # 540 translations
│   ├── myarmy.json       # 487 translations
│   ├── navigation.json   # 8 translations
│   ├── forms.json        # 27 translations
│   ├── errors.json       # 67 translations
│   └── other.json        # 189 translations
└── status.json           # Global progress

```

## Translation Workflow

1. **Extract from Shopify**
   ```bash
   node extract-translations.mjs --type=ONLINE_STORE_THEME --limit=1
   ```

2. **Split into categories**
   ```bash
   node translations/scripts/split-translations.mjs
   ```

3. **Translate with AI**
   ```bash
   # All languages, all categories
   node translations/scripts/translate-file.mjs

   # Specific category
   node translations/scripts/translate-file.mjs --category=myarmy --lang=de
   ```

4. **Check progress**
   ```bash
   node translations/scripts/get-status.mjs --detailed
   ```

5. **Validate quality**
   ```bash
   node translations/scripts/validate-translations.mjs
   ```

6. **Review translations**
   ```bash
   # Interactive review
   node translations/scripts/mark-reviewed.mjs myarmy de --interactive

   # Bulk mark as reviewed
   node translations/scripts/mark-reviewed.mjs checkout it
   ```

7. **Merge for publishing**
   ```bash
   node translations/scripts/merge-back.mjs
   ```

8. **Publish to Shopify**
   ```bash
   node publish-translations.mjs translations-ready.json
   ```

## Status Types

- **pending** - Not yet translated
- **in_progress** - Currently being processed
- **completed** - Translation done, not reviewed
- **reviewed** - Manually verified as correct
- **failed** - Error during translation

## Cost Estimates

Using GPT-4o-mini:
- ~$0.008 per translation
- ~$37 for all 4,686 translations
- Batch processing reduces API calls

## Troubleshooting

### Reset failed translations
```bash
node translations/scripts/reset-failed.mjs
```

### Find specific translation
```bash
node translations/scripts/search-translations.mjs "badge"
node translations/scripts/search-translations.mjs "ton équipement" --lang=de
```

### Validate for issues
```bash
node translations/scripts/validate-translations.mjs --category=myarmy
```

## Environment Setup

Create `translations/config/.env`:
```env
OPENAI_API_KEY=your-api-key
AI_MODEL=gpt-4o-mini
```

## Glossary Management

Key military terms in `glossary.json`:
- 400+ Swiss military terms
- Fixed phrases with exact translations
- Do-not-translate list (MyArmy, Shopify, etc.)

## Brand Guidelines

Defined in `brand.json`:
- Professional yet approachable tone
- Military pride and Swiss quality focus
- Language-specific formatting rules