iOS Translation Tool

Free automatic translation for iOS .xcstrings files using Google Translate

Quickly and 100% free translate your iOS app into multiple languages using Google Translate.

---

✨ Features

• ✅ 100% free (uses Google Translate)
• ✅ Works with any iOS app using .xcstrings
• ✅ Automatic variable preservation (%@, %d, etc.)
• ✅ Rate-limiting protection
• ✅ Automatic backups
• ✅ Resumable on interruption
• ✅ Skip already-translated strings

---

🚀 Quick Start

1. Setup (one-time per project)

# 1. Go to your Xcode project directory
cd /path/to/your/XcodeProject

# 2. Copy the script
cp ~/iOS-Translation-Tool/translate_xcstrings.py .

# 3. Create virtual environment
python3 -m venv .venv

# 4. Activate virtual environment
source .venv/bin/activate

# 5. Install library
pip install deep-translator

2. Test (optional but recommended)

# Test if Google Translate works:
python3 test_translation.py

3. Start translation

# DRY-RUN (preview without saving):
python3 translate_xcstrings.py --dry-run --target ar

# ACTUAL TRANSLATION:
python3 translate_xcstrings.py --target ar

# With custom filename:
python3 translate_xcstrings.py --file Custom.xcstrings --target ar

4. Complete 100%

# Add missing strings for 100% completion:
python3 complete_remaining.py --target ar

---

🌍 Supported Languages

Change the --target parameter:

Language	Code	Example
Arabic	ar	--target ar
French	fr	--target fr
Spanish	es	--target es
Italian	it	--target it
Portuguese	pt	--target pt
Russian	ru	--target ru
Chinese (Simplified)	zh-CN	--target zh-CN
Japanese	ja	--target ja
Korean	ko	--target ko
Turkish	tr	--target tr
Dutch	nl	--target nl
Polish	pl	--target pl
Swedish	sv	--target sv

Complete list of language codes

---

⚠️ IMPORTANT: English Translation

Don't translate to English if your keys are already in English!

If your .xcstrings file uses English keys like this:

{
  "strings": {
    "Save": { ... },
    "Cancel": { ... }
  }
}

Skip --target en! Xcode automatically uses the key as English fallback.

Only translate to English if your keys are in another language (e.g., German keys need English translation).

See README_ENGLISH_KEYS.md for detailed explanation.

---

📱 Add to Your App

After translation, make the language available in your app:

1. Extend LanguageManager.swift

enum Language: String, CaseIterable {
    case system = "system"
    case english = "en"
    case german = "de"
    case arabic = "ar"  // NEW

    var localizedDisplayName: String {
        switch self {
        case .system:
            let systemLanguage = Locale.preferredLanguages.first?.prefix(2) ?? "en"
            return NSLocalizedString("System", comment: "") + " (\(systemLanguage.uppercased()))"
        case .english:
            return "English"
        case .german:
            return "Deutsch"
        case .arabic:
            return "العربية"  // NEW
        }
    }
}

2. Check Info.plist

<key>CFBundleLocalizations</key>
<array>
    <string>en</string>
    <string>de</string>
    <string>ar</string>  <!-- NEW -->
</array>

3. Test App

• Settings → Language → Select new language
• App will automatically restart
• UI will mirror for RTL languages (Arabic, Hebrew)

---

⚙️ Advanced Options

Parameters

--file PATH          Path to .xcstrings file (default: Localizable.xcstrings)
--target LANG        Target language (e.g., ar, fr, es)
--source LANG        Source language (default: en)
--dry-run            Preview without saving

Examples

# Translate German → French:
python3 translate_xcstrings.py --source de --target fr

# Multiple languages in sequence:
python3 translate_xcstrings.py --target fr
python3 translate_xcstrings.py --target es
python3 translate_xcstrings.py --target it

---

🔧 Troubleshooting

"ImportError: deep-translator"

source .venv/bin/activate
pip install deep-translator

"File not found: Localizable.xcstrings"

# Find your .xcstrings file:
find . -name "*.xcstrings"

# Use --file parameter:
python3 translate_xcstrings.py --file "Path/to/File.xcstrings" --target ar

"Rate limit" / Too many requests

Script automatically pauses every 10 strings. For very large projects (>1000 strings):

• Wait 5 minutes between runs
• Or translate in multiple sessions

Google Translate temporarily unavailable

Wait 1-2 minutes and try again.

---

📊 Typical Times

Number of Strings	Duration	Cost
100	~2 min	$0
500	~8 min	$0
1000	~15 min	$0
1500	~25 min	$0

---

💡 Best Practices

1. Mark non-translatable strings

// Emails, URLs, technical values:
Text(verbatim: "user@example.com")  // ✅ Not translatable

// Instead of:
Text("user@example.com")  // ❌ Will end up in string catalog

2. Backup before translation

Script automatically creates .backup files. Additionally:

# Before translation:
cp Localizable.xcstrings Localizable.xcstrings.before_arabic

# Restore if needed:
cp Localizable.xcstrings.before_arabic Localizable.xcstrings

3. Quality control

After translation:

1. Open Xcode → Localizable.xcstrings
2. Filter to new language
3. Check samples (first 10-20 strings)
4. Test app with new language

4. Git Ignore

Add to .gitignore:

# Translation Scripts
*.py
.venv/
translation_*.log
*.xcstrings.backup

---

📝 Files Included

• ✅ translate_xcstrings.py - Main translation script
• ✅ complete_remaining.py - Script for 100% completion
• ✅ test_translation.py - Test script
• ✅ translate_multiple.sh - Batch script for multiple languages
• ✅ LanguageManager_Example.swift - Swift code example
• ✅ requirements.txt - Python dependencies
• ✅ .gitignore - Git ignore template

---

🎯 Workflow Summary

1. Copy Script   →  2. Setup venv   →  3. Install lib
        ↓                                      ↓
4. Test          →  5. Translate     →  6. Complete 100%
        ↓                                      ↓
7. Add to App    →  8. Test in Xcode →  9. Ready for Store!

---

📖 Documentation

• README_ENGLISH_KEYS.md - Important info about English translation
• QUICKSTART.md - Quick start guide (German)
• EXAMPLES.md - Practical examples (German)

---

📄 License

MIT License - Free to use for all your iOS projects.

---

🙏 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

---

⭐ Support

If this tool helps you, please star this repository!

---

Happy translating! 🚀