🧠 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

npm install @akson/cortex-shopify-translations

2. Initial Setup

npm run setup

This will:

• Create necessary directories
• Copy configuration templates
• Generate .env file template

3. Configuration

Edit .env file:

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

npm run extract
# or
node extract-translations.mjs

Other resource types:

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

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:

npm run publish
# or
node publish-translations.mjs --force

Other resource types:

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

# 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

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

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

Product Workflow (v2.3.0)

Two-phase product translation workflow for updating primary titles and translations:

The Problem

When English is set as primary language in Shopify, product titles need to be in English. Then translations (FR, DE, IT) are added via the Translation API.

The Solution

# Translate all products using mappings
npx @akson/cortex-shopify-translations product-workflow --from-mappings

# Translate single product by handle
npx @akson/cortex-shopify-translations product-workflow --handle badge-custom

# Translate by product ID
npx @akson/cortex-shopify-translations product-workflow \
  --id gid://shopify/Product/123 \
  --title "Custom Badge"

Product Mappings

Create translations/config/product-mappings.json:

{
  "exact": {
    "Badge personnalisé": {
      "en": "Custom Badge",
      "de": "Individuelles Abzeichen",
      "it": "Badge personalizzato"
    }
  }
}

Verification (v2.3.0)

Verify translations across all languages:

# Verify single product
npx @akson/cortex-shopify-translations verify --handle badge-custom

# Verify by resource ID
npx @akson/cortex-shopify-translations verify --id gid://shopify/Product/123

# Verify multiple products
npx @akson/cortex-shopify-translations verify --type product --limit 20

# Generate verification report
npx @akson/cortex-shopify-translations verify --type product --report --output report.json

New GraphQL Client Methods (v2.3.0)

For programmatic usage:

import { createGraphQLClient } from '@akson/cortex-shopify-translations/client';

const client = createGraphQLClient();

// Update primary product title
await client.updateProductTitle('gid://shopify/Product/123', 'Custom Badge');

// Find products by title
const products = await client.findProductsByTitle('Badge');

// Get product by handle
const product = await client.getProductByHandle('badge-custom');

// Verify translations
const verification = await client.verifyTranslations('gid://shopify/Product/123');

// Get fresh content with digest
const content = await client.getTranslatableContent('gid://shopify/Product/123');

// Register single translation (fetches fresh digest)
await client.registerSingleTranslation(
  'gid://shopify/Product/123',
  'de',
  'title',
  'Individuelles Abzeichen'
);

Changelog

v2.3.0

• Added product-workflow command for two-phase product translations
• Added verify command for translation verification
• Added product mappings support (product-mappings.json)
• New GraphQL client methods: updateProductTitle, findProductsByTitle, getProductByHandle, verifyTranslations, getTranslatableContent, registerSingleTranslation

v2.2.0

• AI-powered translations with OpenAI GPT-4o-mini
• Automatic resumption and progress tracking
• Status tracking per language

v2.0.0

• Initial multi-language support
• Extract/publish workflow
• CLI tools