Skip to content

Quick Start

Jump to bottom
EhsanAzish80 edited this page Dec 15, 2025 · 1 revision

Quick Start Guide

Get up and running with auto-translate-localizables in 5 minutes.

Prerequisites

✅ Python 3.7+ installed
✅ pip package manager
✅ Xcode project with localization files

Step 1: Install (30 seconds)

# From GitHub (current method)
git clone https://github.com/EhsanAzish80/Auto-Translate-localizables.git
cd Auto-Translate-localizables
pip install -e .

# Verify
auto-translate-xcloc --version

Step 2: Export from Xcode (2 minutes)

  1. Open your Xcode project
  2. Product → Export Localizations...
  3. Choose location (e.g., ~/Desktop/Localization)
  4. Select languages to export
  5. Click Export

You should now have a folder structure like:

Localization/
├── en.xcloc/
├── de.xcloc/
├── fr.xcloc/
└── es.xcloc/

Step 3: Translate (1 minute)

Basic Translation

auto-translate-xcloc --workspace ~/Desktop/Localization

This will:

  • ✅ Find all .xcloc folders
  • ✅ Translate all languages (except English)
  • ✅ Validate placeholder preservation
  • ✅ Save translated XLIFF files

Safe Preview First

auto-translate-xcloc --workspace ~/Desktop/Localization --dry-run

This shows what would be translated without making changes.

Step 4: Import Back to Xcode (1 minute)

  1. In Xcode: Product → Import Localizations...
  2. Select the Localization folder
  3. Review changes
  4. Click Import

✅ Done! Your app now has translated strings.

Common Commands

Translate Everything

auto-translate-xcloc --workspace ~/Desktop/Localization

Dry Run (Preview)

auto-translate-xcloc --workspace ~/Desktop/Localization --dry-run

Only Missing Strings

auto-translate-xcloc --workspace ~/Desktop/Localization --only-missing

Specific Languages Only

auto-translate-xcloc --workspace ~/Desktop/Localization --only de fr es

List Supported Languages

auto-translate-xcloc --list-languages

Expected Output

============================================================
XLIFF Bulk Translation
============================================================
Workspace: /Users/you/Desktop/Localization
Skipping: en
Mode: TRANSLATION
============================================================

============================================================
Processing DE -> de
============================================================

[FILE] Localizable.xliff
  [✓] Translated 245 entries (0 errors)

============================================================
Processing FR -> fr
============================================================

[FILE] Localizable.xliff
  [✓] Translated 245 entries (0 errors)

============================================================
TRANSLATION SUMMARY
============================================================

[✓] de        ->  245 translated,    0 errors
[✓] fr        ->  245 translated,    0 errors

============================================================
TOTAL: 490 entries translated
       0 errors
============================================================

Troubleshooting Quick Fixes

"No .xcloc folders found"

Make sure you're pointing to the correct directory:

ls ~/Desktop/Localization
# Should show: en.xcloc de.xcloc fr.xcloc

"Command not found: auto-translate-xcloc"

Add to PATH:

export PATH="$HOME/.local/bin:$PATH"
# Or for macOS:
export PATH="$HOME/Library/Python/3.11/bin:$PATH"

Placeholder Errors

Use --dry-run first to check:

auto-translate-xcloc --workspace ~/Desktop/Localization --dry-run

Next Steps

🎉 You're ready! Here's what to explore next:

Pro Tips

�� Use --only-missing for incremental updates
💡 Use --dry-run before making changes
💡 Keep English (en) in skip list - it's usually your source
💡 Review git diff after translating to check changes
💡 Use --fail-on-placeholder-mismatch in CI pipelines

Questions? See FAQ or Troubleshooting

Clone this wiki locally