imager/scripts

Translation Sync Scripts

This directory contains automation scripts for managing i18n translations.

sync-locales.js

Automatically syncs all translation files with src/locales/en.json (the source of truth) and translates missing keys using AI.

Features

• Automatic Detection: Finds missing keys in all locale files
• AI Translation: Uses OpenAI API to automatically translate new keys with high quality
• Context-Aware: Provides section/key context to the AI for better translations
• Placeholder Preservation: Maintains i18next placeholders like {{count}} and {{boardName}}
• Adaptive Rate Limiting: Automatically adjusts based on model and payment tier
• Error Handling: Falls back to TODO: prefix if translation fails
• Smart Prompts: Uses specialized prompts for technical UI translation

Usage

Local Development

# Basic usage (requires OpenAI API key)
export OPENAI_API_KEY=sk-...
node scripts/sync-locales.js

# With custom model (default: gpt-4o-mini)
OPENAI_MODEL=gpt-4o node scripts/sync-locales.js

# With custom OpenAI-compatible API endpoint
OPENAI_API=https://api.openai.com/v1 node scripts/sync-locales.js

# For paid tier (much faster - 50-100x speedup)
OPENAI_TIER=paid node scripts/sync-locales.js

# Retry failed translations (keys marked with TODO:)
RETRY_FAILED=true node scripts/sync-locales.js

GitHub Actions

The workflow runs automatically:

• Daily at 00:00 UTC
• On push to the branch
• On manual trigger via workflow_dispatch

Configuration

Environment Variables

Variable	Description	Default	Required
OPENAI_API_KEY	OpenAI API key	-	Yes
OPENAI_MODEL	Model to use for translation	gpt-4o-mini	No
OPENAI_API	API endpoint URL	https://api.openai.com/v1	No
OPENAI_TIER	Account tier for rate limits	free	No
RETRY_FAILED	Retry keys marked with TODO:	false	No

GitHub Secrets/Variables

To configure the GitHub Action:

1. Required - Add API key:

   gh secret set OPENAI_API_KEY
   

2. Optional - Custom model (for cost/quality tuning):

   gh variable set OPENAI_MODEL --value "gpt-4o-mini"
   

3. Optional - Custom endpoint (for OpenAI-compatible APIs):

   gh variable set OPENAI_API --value "https://api.openai.com/v1"
   

4. Optional - Set account tier (for faster translations with paid account):

   gh variable set OPENAI_TIER --value "paid"
   

5. Optional - Retry failed translations (re-attempt keys marked with TODO:):

   gh variable set RETRY_FAILED --value "true"
   

OpenAI Setup

Getting an API Key

1. Visit platform.openai.com
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key
5. Add it to your environment or GitHub secrets

Account Tier & Rate Limits

The script automatically adjusts speed based on your account tier:

Tier	RPM Limit	Batch Size	Delay	100 Keys Time
Free	3/min	1	21s	~35 min
Paid (Tier 1-2)	200/min	50	300ms	~1 min
Paid (Tier 3-5)	500/min	50	120ms	~30 sec

To use paid tier rates:

1. Add a payment method to your OpenAI account (even $5 works)
2. Set OPENAI_TIER=paid environment variable

Recommendation: With just a $5 balance, you get Tier 1-2 rates which are 65x faster than free tier.

Choosing a Model

Model	Cost	Quality	Speed	Best For
gpt-4o-mini	Low	High	Fast	Most translations (default)
gpt-4o	Medium	Very High	Fast	Complex UI text
gpt-3.5-turbo	Very Low	Medium	Very Fast	Simple translations

Recommendation: Start with gpt-4o-mini for the best balance of cost, quality, and speed.

Supported Languages

Code	Language
de	German
es	Spanish
fr	French
it	Italian
ja	Japanese
ko	Korean
nl	Dutch
pl	Polish
pt	Portuguese
ru	Russian
sl	Slovenian
tr	Turkish
uk	Ukrainian
zh	Chinese (Simplified)

Output

The script will:

1. ✅ Show which keys are missing for each language
2. 🤖 Translate missing keys with OpenAI
3. 📊 Show translation statistics (success/failure)
4. ⚠️ Warn about any translation failures
5. 💾 Update locale files with translated content
6. 🔍 Exit with code 1 if changes were made (useful for CI/CD)

Example Output

🔍 Syncing translation files with en.json (source of truth)

🤖 Using OpenAI API: https://api.openai.com/v1
📦 Model: gpt-4o-mini
✅ API key is configured

✅ Source file has 93 keys

📝 Processing de (German)...
  ✅ de is up to date (93 keys)

📝 Processing hr (Croatian)...
  ⚠️  Found 64 missing keys
  🤖 Translating 64 strings with OpenAI...
  ✅ Updated hr with 64 new keys

✨ Translation files updated successfully!

📊 Summary:
  - Total translated: 64 keys
  - Please review translations for accuracy and context

AI Translation Features

The script uses specialized prompts to ensure:

1. Context Awareness: Provides section/key context for each translation
2. Technical Terminology: Knows when to keep terms like "Flash", "SD card", "USB" in English
3. Placeholder Preservation: Maintains {{variables}} exactly as they appear
4. UI Appropriateness: Uses concise, natural text for buttons and labels
5. Plural Forms: Handles i18next plural suffixes (_one, _other) correctly
6. Consistent Tone: Maintains formal but friendly tone throughout

Best Practices

1. Review Translations: AI translations are excellent but may need context-specific adjustments
2. Test in App: Always test translations in the actual application
3. Handle Plurals: The script preserves _one and _other suffixes for plural forms
4. Check Placeholders: Verify that {{variables}} are correctly preserved
5. Cultural Nuances: Review translations for cultural appropriateness
6. Cost Management: Use gpt-4o-mini for best cost/quality balance

Troubleshooting

API Key Not Found

❌ OPENAI_API_KEY is not set!

Solution: Set the environment variable or GitHub secret:

export OPENAI_API_KEY=sk-...

Translation Failures

If some translations fail with TODO::

• Check your API key has sufficient credits
• Verify API endpoint is accessible
• Check rate limits (especially for larger translation batches

Poor Quality Translations

If translations seem off:

• The AI might lack specific UI context
• Try a more capable model like gpt-4o
• Manually edit the JSON files to fix issues
• Consider the translation context provided in the prompt

Cost Concerns

For cost optimization:

• Use gpt-4o-mini (very cost-effective)
• Run the script less frequently
• Review and merge translations in batches
• Consider caching previous translations

Cost Estimation

Approximate costs for translating missing keys (using gpt-4o-mini):

• 10 keys: ~$0.00001
• 50 keys: ~$0.00005
• 100 keys: ~$0.0001

Costs vary based on text length and model used.