Home
Welcome to the comprehensive documentation for auto-translate-localizables!
A production-ready Python package that automates Xcode .xcloc localization using reproducible, CI-friendly machine translation—built for real iOS teams.
- Installation - How to install the package
- Quick Start - Get up and running in 5 minutes
- Your First Translation - Step-by-step tutorial
- CLI Reference - Complete command-line reference
- Python API - Using as a Python library
- GUI Application - Desktop application guide
- Workflow Integration - Xcode export/import workflow
- GitHub Actions Setup - Automated CI/CD translation
- Auto-Translate Workflow - Automatic PR creation
- Validation Workflow - PR validation setup
- Placeholder Preservation - How placeholders are protected
- Language Support - All 113 supported languages
- Safety Features - Validation, backups, error handling
- CI-CD Modes - Dry-run, only-missing, fail-on-error modes
- Provider Architecture - Translation provider system
- Error Handling - How errors are handled and reported
- Performance Tips - Optimizing for large projects
- Custom Configuration - Advanced configuration options
- Troubleshooting - Common issues and solutions
- FAQ - Frequently asked questions
- Contributing - How to contribute
- Changelog - Version history and updates
Problem: Xcode exports .xcloc files for localization, but Apple provides no bulk translation workflow. Manual translation of hundreds of strings is tedious and error-prone.
Solution: This tool automates the entire process while maintaining safety through strict placeholder validation, XLIFF structure preservation, and CI-friendly modes.
- Automatically detects Xcode .xcloc folders
- Identifies source and target languages
- Finds all XLIFF files recursively
- Validates placeholder preservation (
%@,%d,{0}, etc.) - XLIFF structure validation
- Automatic backup and restore on errors
- Dry-run mode for safe preview
- 113 languages with explicit mappings
- Regional variants (zh-Hans, zh-Hant, pt-BR, es-419)
- No Google auto-guess surprises
-
--dry-runfor safe testing -
--only-missingfor incremental updates -
--fail-on-placeholder-mismatchfor strict validation - Proper exit codes (0, 1, 130)
- GitHub Actions workflows included
-
CLI:
auto-translate-xcloccommand - Python API: Import and use in your scripts
- GUI: Desktop application with progress tracking
- GitHub Actions: Automated PR creation
pip install auto-translate-localizables# Translate all languages in workspace
auto-translate-xcloc --workspace /path/to/localization
# Preview without changes
auto-translate-xcloc --workspace /path/to/localization --dry-run
# Only translate missing strings
auto-translate-xcloc --workspace /path/to/localization --only-missingfrom auto_translate_localizables import XLIFFTranslator
translator = XLIFFTranslator(workspace_dir="/path/to/localization")
results = translator.process_all_languages(skip_languages=['en'])- I want to install the tool → Installation
- I want to translate my first project → Your First Translation
- I want to automate with GitHub Actions → GitHub Actions Setup
- I need all CLI options → CLI Reference
- I want to use it in Python → Python API
- Something went wrong → Troubleshooting
- I have questions → FAQ
- Placeholder handling → Placeholder Preservation
- Supported languages → Language Support
- Safety mechanisms → Safety Features
- CI/CD integration → CI-CD Modes
- Error messages → Error Handling
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: ehsanazish80@gmail.com
MIT License - see LICENSE
Ready to get started? → Installation → Quick Start