🌍 auto-translate-localizables

Automates Xcode .xcloc localization using reproducible, CI-friendly machine translation—built for real iOS teams.

Why This Exists

Xcode exports .xcloc, but Apple provides no bulk translation workflow. This tool fills that gap.

If you've ever manually translated hundreds of localization strings, or copy-pasted between Xcode and Google Translate, you know the pain. This tool automates the entire workflow while maintaining safety and reproducibility.

The Problem → Solution

Before 😤

1. Export .xcloc from Xcode
2. Open each language's XLIFF file
3. Copy string → Google Translate → Paste
4. Repeat 500 times
5. Hope you didn't break any %@ placeholders
6. Import back into Xcode
7. Build fails because placeholders got mangled

After ✨

auto-translate-xcloc --workspace ./localization

That's it. All languages translated. Placeholders preserved. XLIFF structure validated. Ready for Xcode import.

✨ Features

🎯 Zero Configuration — Automatically detects languages and structure
🛡️ Strict Placeholder Preservation — Validates %@, %d, {0}, etc. are preserved exactly
🌐 100+ Languages — Supports all major languages via Google Translate
⚡ CI-Friendly — --dry-run, --only-missing, --fail-on-placeholder-mismatch modes
🔍 Smart Translation — Skips units (kg, ml), preserves formatting, handles special characters
💾 Safe by Default — Validates XLIFF structure, auto-restores on corruption
📦 Proper Package — Install via pip, use as CLI or Python library
🎯 Xcode Compatible — Works with iOS, macOS, watchOS, tvOS projects

🚀 Installation

Install from PyPI (recommended)

pip install auto-translate-localizables

Install from source

git clone https://github.com/EhsanAzish80/Auto-Translate-localizables
cd Auto-Translate-localizables
pip install -e .

Verify installation

auto-translate-xcloc --version

📖 Usage

Basic Usage

# Translate all languages
auto-translate-xcloc --workspace /path/to/localization

# Dry run (see what would happen)
auto-translate-xcloc --workspace ./localization --dry-run

# Only translate missing strings (preserve existing)
auto-translate-xcloc --workspace ./localization --only-missing

Advanced Usage

# Translate specific languages only
auto-translate-xcloc --workspace ./localization --only de fr es

# Skip certain languages
auto-translate-xcloc --workspace ./localization --skip en ar

# CI mode: fail on placeholder mismatches
auto-translate-xcloc --workspace ./localization --fail-on-placeholder-mismatch

# List all supported languages
auto-translate-xcloc --list-languages

Expected Directory Structure

workspace/
├── en.xcloc/
│   └── Localized Contents/
│       └── en.xliff
├── de.xcloc/
│   └── Localized Contents/
│       └── de.xliff
├── fr.xcloc/
│   └── Localized Contents/
│       └── fr.xliff
└── es.xcloc/
    └── Localized Contents/
        └── es.xliff

This is the standard structure Xcode creates when you export localizations.

🔧 As a Python Library

from auto_translate_localizables import XLIFFTranslator

# Create translator
translator = XLIFFTranslator(
    workspace_dir="/path/to/localization",
    fail_on_placeholder_mismatch=True
)

# Translate all languages
results = translator.process_all_languages(
    skip_languages=['en'],
    dry_run=False,
    only_missing=False
)

# Process specific language
results = translator.process_language_folder('de', dry_run=False)

# Check for errors
if translator.errors:
    for error in translator.errors:
        print(f"Error: {error['file']}: {error['error']}")

🎯 Workflow Integration

Xcode Export → Translate → Import

# 1. Export from Xcode
# Product → Export Localizations...

# 2. Translate
auto-translate-xcloc --workspace ./LocalizationExport

# 3. Import back to Xcode
# Product → Import Localizations...

With Version Control

# After exporting from Xcode
git add localization/*.xcloc
auto-translate-xcloc --workspace ./localization
git diff  # Review translations
git commit -m "Update translations"

🤖 CI/CD Integration

This repository includes ready-to-use GitHub Actions for automated translation workflows.

Included Workflows

1. Auto-Translate (`.github/workflows/auto-translate.yml`)

Automatically translates localization files when English changes or on manual trigger.

Triggers:

✅ When en.xcloc files change
✅ Manual workflow dispatch with options

Features:

Creates Pull Request with translated strings
Validates placeholder preservation
Only translates missing strings by default
Configurable language selection

Manual Trigger Options:

Languages: Specify "de fr es" or "all"
Only missing: true/false
Create PR: true/false (direct commit option)

2. Validate Translations (`.github/workflows/validate-translations.yml`)

Validates translation quality on Pull Requests.

Runs on:

✅ Any PR that modifies .xcloc or .xliff files

Validates:

✅ Placeholder preservation
✅ XLIFF syntax correctness

Quick Setup

The workflows are already configured in this repository. Just:

Push to GitHub - workflows are ready to use
Make a change to en.xcloc files - auto-translation triggers
Review the PR - translations are validated and ready

Manual Trigger

Go to Actions → Auto-Translate Localizations → Run workflow

Example Workflow Output

🌍 Auto-translate localization files

✅ Translated 245 entries (0 errors)
✅ Placeholder validation passed
✅ XLIFF structure validated
📝 Pull Request created: #123

🛡️ Safety Features

Placeholder Preservation

The tool strictly validates that placeholders are preserved:

# Original
"You have %d items in %@"

# ✅ Valid translation (German)
"Sie haben %d Artikel in %@"

# ❌ Invalid - placeholder count mismatch
"Sie haben Artikel in %@"  # Missing %d

# ❌ Invalid - placeholder type changed
"Sie haben %@ Artikel in %d"  # Swapped types

XLIFF Validation

Validates XML structure before and after translation
Auto-restores original file if corruption detected
Preserves XML namespaces and attributes
Maintains Xcode-compatible formatting

Rate Limiting

Automatic delays between translations
Prevents Google Translate rate limiting
Configurable batch sizes

🌍 Supported Languages

100+ languages supported. Run auto-translate-xcloc --list-languages for full list.

Common examples:

🇩🇪 German (de)
🇫🇷 French (fr)
🇪🇸 Spanish (es, es-419, es-MX)
🇨🇳 Chinese Simplified (zh-Hans)
🇹🇼 Chinese Traditional (zh-Hant)
🇯🇵 Japanese (ja)
🇰🇷 Korean (ko)
🇷🇺 Russian (ru)
🇵🇹 Portuguese (pt, pt-BR, pt-PT)
And many more...

⚠️ Important Disclaimers

Machine Translation

This tool uses Google Translate. Output quality varies by language. Always have translations reviewed by native speakers before shipping to production.

Placeholder Limitations

While the tool validates placeholder preservation, it cannot validate placeholder position correctness in all languages. Some languages require different word orders.

Rate Limits

Google Translate has rate limits. For very large projects (1000+ strings), run with --only-missing on subsequent runs.

🔄 Development Workflow

Setting Up Development Environment

# Clone repository
git clone https://github.com/EhsanAzish80/Auto-Translate-localizables
cd Auto-Translate-localizables

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest

# Format code
black .

# Type checking
mypy auto_translate_localizables

Package Structure

auto-translate-localizables/
├── auto_translate_localizables/
│   ├── __init__.py          # Package exports
│   ├── cli.py               # CLI entry point
│   ├── translator.py        # Core translation logic
│   └── language_map.py      # Language code mappings
├── pyproject.toml           # Modern Python packaging
├── README.md
└── LICENSE

🎓 Examples

Example 1: First-Time Translation

# Export from Xcode to ~/Desktop/Localization
# Run translation
auto-translate-xcloc --workspace ~/Desktop/Localization

# Output:
# ============================================================
# XLIFF Bulk Translation
# ============================================================
# Workspace: /Users/you/Desktop/Localization
# Skipping: en
# Mode: TRANSLATION
# ============================================================
# 
# ============================================================
# Processing DE -> de
# ============================================================
# 
# [FILE] Localizable.xliff
#   [✓] Translated 245 entries (0 errors)
# 
# [✓] de        ->  245 translated,    0 errors
# 
# ============================================================
# TOTAL: 245 entries translated
#        0 errors
# ============================================================

Example 2: Update Only Missing

# You've added 20 new strings to English
auto-translate-xcloc --workspace ./localization --only-missing

# Only translates the 20 new strings, preserves existing translations

Example 3: CI Validation

# In CI pipeline
auto-translate-xcloc \
  --workspace ./localization \
  --dry-run \
  --fail-on-placeholder-mismatch

# Exit code 0 = all good
# Exit code 1 = validation errors found

🤝 Contributing

Contributions welcome! This project follows standard Python best practices.

Areas for contribution:

DeepL translation provider support
Azure Translator support
Custom terminology/glossary support
Translation memory (TM) integration
Improved placeholder validation
GUI improvements
Test coverage

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with:

deep-translator - Translation API wrapper
lxml - Robust XML processing
Apple Xcode XLIFF format

📧 Contact & Support

GitHub Issues: Report bugs or request features
Author: Ehsan Azish
Email: ehsanazish80@gmail.com

🚀 Roadmap

Phase 2 - Automation (Next)

GitHub Action for automated translation
Pre-commit hook integration
Translation quality scoring

Phase 3 - Translation Quality

DeepL provider support
OpenAI GPT translation option
Per-language provider override
Custom terminology support

Phase 4 - Enterprise Features

Translation memory (TM) support
Terminology glossaries
Translation review workflow
Analytics and reporting

Star ⭐ this repo if it saved you time!

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
auto_translate_localizables		auto_translate_localizables
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
EXAMPLES.py		EXAMPLES.py
INSTALL_GUIDE.md		INSTALL_GUIDE.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
RELEASE_READY.md		RELEASE_READY.md
install_dev.sh		install_dev.sh
localization_app.py		localization_app.py
pyproject.toml		pyproject.toml
release.sh		release.sh
requirements.txt		requirements.txt
run.sh		run.sh
setup.sh		setup.sh
translate_xliff.py		translate_xliff.py

Folders and files

Latest commit

History

Repository files navigation