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

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

# 🧠 Cortex Shopify Translations

A brand-agnostic Shopify translation management system with AI-powered translation, configurable multi-language support, and comprehensive CLI tools.

## Features

- 🌍 Multi-language translation management (FR, DE, IT, EN, and more)
- 🤖 AI-powered translations with OpenAI GPT-4o-mini (v2.0+)
- 📦 Support for products, collections, pages, and theme translations
- 🔧 Comprehensive CLI tools for extraction, translation, and publishing
- 🎯 Automatic resumption and progress tracking
- ✅ Swiss military terminology built-in
- 💾 Single-file mode with incremental saving
- 📊 Status tracking per field and language

## Quick Start

### 1. Installation

```bash
npm install @akson/cortex-shopify-translations
```

### 2. Initial Setup

```bash
npm run setup
```

This will:
- Create necessary directories
- Copy configuration templates
- Generate .env file template

### 3. Configuration

**Edit `.env` file:**
```env
# Shopify Store Configuration
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_your_token

# Language Configuration
SUPPORTED_LANGUAGES=fr,de,it,en
PRIMARY_LANGUAGE=en

# OpenAI Configuration (for AI translations)
OPENAI_API_KEY=your-openai-api-key
```

**Edit `translations/config/brand.json`:**
Customize the brand template with your company's voice, tone, and style guidelines.

### 4. Set Primary Language in Shopify

- Go to **Shopify Admin → Settings → Languages**
- Set your primary language as default
- Enable all target languages

## Usage

### 1. Extract Translations

**Theme translations (default):**
```bash
npm run extract
# or
node extract-translations.mjs
```

**Other resource types:**
```bash
# Products
npm run extract:product
node extract-translations.mjs product

# Collections
npm run extract:collection
node extract-translations.mjs collection

# Pages
npm run extract:page
node extract-translations.mjs page

# See all available types
npm run extract:help
```

**Available Resource Types:**
- `online_store_theme` (default) - Theme translations
- `product` - Product titles, descriptions, etc.
- `collection` - Collection names, descriptions
- `page` - Static page content
- `article` - Blog articles
- `blog` - Blog metadata
- `shop` - Shop settings
- `shop_policy` - Store policies
- And more... (use `--help` for full list)

### 2. AI-Powered Translation (New in v2.0)

**Translate with OpenAI GPT-4o-mini:**
```bash
npm run translate
# or
npx @akson/cortex-shopify-translations translate translations-to-edit.json

# Options:
# --force    Retranslate all items (ignore existing)
# --verbose  Show detailed progress
```

Features:
- Automatic resumption (picks up where it left off)
- Status tracking per language (`de_status`, `it_status`, `en_status`)
- Single-file mode (works directly on the file)
- Swiss military terminology built-in
- Batch processing with rate limiting

### 3. Manual Editing (Alternative)
Edit the `translations-to-edit.json` file:
- `{source}_original` = Source language text (don't change)
- `{target}_fixed` = Your corrected translations for each target language

Example with French→German/Italian/English:
- `fr_original` = French base text (don't change)
- `de_fixed` = Your corrected German translation
- `it_fixed` = Your corrected Italian translation
- `en_fixed` = Your corrected English translation

### 4. Publish Changes

**Theme translations:**
```bash
npm run publish
# or
node publish-translations.mjs --force
```

**Other resource types:**
```bash
# Products
npm run publish:product
node publish-translations.mjs product --force

# Collections
npm run publish:collection
node publish-translations.mjs collection --force

# Pages
npm run publish:page
node publish-translations.mjs page --force
```

## Example Fix

**Source (French):** `"TA SECTION, TON EQUIPEMENT"`
**Bad German:** `"Ta Zug, Tonne Ausrüstung"`
**Fixed German:** `"TA SEKTION, DEINE AUSRÜSTUNG"`

Edit the `de_fixed` field and run `npm run publish`.

## Language Configuration

Supports any source→target language combination:

```env
# English to multiple languages
SHOPIFY_SOURCE_LANGUAGE=en
SHOPIFY_TARGET_LANGUAGES=fr,de,es,it

# German to French and Italian
SHOPIFY_SOURCE_LANGUAGE=de
SHOPIFY_TARGET_LANGUAGES=fr,it

# Spanish to English only
SHOPIFY_SOURCE_LANGUAGE=es
SHOPIFY_TARGET_LANGUAGES=en
```

## Generated Files

**Theme translations:**
- `translations-to-edit.json` - Editable theme translations
- `translations-publish-report.json` - Publishing results

**Other resource types:**
- `{type}-translations-to-edit.json` - Editable translations (e.g., `product-translations-to-edit.json`)
- `{type}-translations-publish-report.json` - Publishing results

**Scripts:**
- `extract-translations.mjs` - Extracts translations from Shopify
- `translate-with-ai.mjs` - AI-powered translation with OpenAI (v2.0+)
- `publish-translations.mjs` - Publishes corrections back to Shopify

## Workflows

**AI-Powered Workflow (Recommended):**
1. `npm run extract` → Creates `translations-to-edit.json`
2. `npm run translate` → AI translates all missing translations
3. `npm run publish` → Updates Shopify store

**Manual Workflow:**
1. `npm run extract` → Creates `translations-to-edit.json`
2. Edit file manually
3. `npm run publish` → Updates Shopify store

**Product translations:**
1. `npm run extract:product` → Creates `product-translations-to-edit.json`
2. `npm run translate product-translations-to-edit.json` → AI translates
3. `npm run publish:product` → Updates Shopify store

**Custom resource type:**
1. `node extract-translations.mjs {type}` → Creates `{type}-translations-to-edit.json`
2. `npx @akson/cortex-shopify-translations translate {type}-translations-to-edit.json`
3. `node publish-translations.mjs {type} --force` → Updates Shopify store

That's it! 🎉

## Help & Documentation

```bash
# See all available resource types
node extract-translations.mjs --help

# Publishing help
node publish-translations.mjs --help
```