XLIFF Translator

A command-line tool to translate XLIFF files using Claude AI. This tool is specifically designed to work with XLIFF files generated by Xcode.

中文文档

Table of Contents

• Installation
• Usage
• Working with Xcode Localizations
  • Exporting XLIFF Files
  • Importing Translated Files
• Options
• App Context Configuration
• Translation Prompts
• Helper Scripts
  • Export Localizations
  • Import Localizations

Installation

1. Clone this repository
2. Install dependencies:

   pip install -r requirements.txt

3. Create a .env file in the project root and add your Claude API key:

   echo "CLAUDE_API_KEY=your_api_key_here" > .env

4. Copy the example app context file and customize it for your app:

   cp app_context.example.yaml app_context.yaml

   Then edit app_context.yaml with your app's specific details. This file will be ignored by git to protect your app's information.

Usage

Single file mode:

python main.py --input path/to/file.xliff --target-language es

Xcode export folder mode:

# Translate all languages
python main.py --folder path/to/export/folder

# Translate specific languages only
python main.py --folder path/to/export/folder --languages "es,fr,ja"

Working with Xcode Localizations

Exporting XLIFF Files

You can export XLIFF files from your Xcode project using a simple command:

# Export all languages
xcodebuild -exportLocalizations -project "YourProject.xcodeproj" -localizationPath ./Localizations

# Export specific language
xcodebuild -exportLocalizations -project "YourProject.xcodeproj" -localizationPath ./Localizations -exportLanguage fr

Importing Translated Files

While Xcode (both GUI and command line) only supports importing one language at a time, we provide a script to batch import all translated languages at once:

1. Copy the example script:

   cp scripts/import_localizations.example.sh scripts/import_localizations.sh

2. Edit the script to set your paths:

   LOCALIZATIONS_DIR="path/to/your/localizations/folder"  # Where your .xcloc files are
   PROJECT_PATH="path/to/your/Project.xcodeproj"         # Your Xcode project file

3. Make the script executable and run it:

   chmod +x scripts/import_localizations.sh
   ./scripts/import_localizations.sh

The script will automatically find and import all translated files (excluding en.xcloc) back into your project, saving you from having to import each language manually.

Options

• --input: Single XLIFF file to translate (will be updated in place, backup created as .bak)
• --folder: Xcode export folder containing .xcloc folders (alternative to --input)
• --target-language: Target language code (required for single file mode)
• --languages: Comma-separated list of language codes to process (optional, folder mode only)
• --context-file: Path to app context YAML file (default: app_context.yaml)
• --prompts-file: Path to prompts YAML file (default: prompts.yaml or prompts.example.yaml)
• --translate-all: Translate all strings, including already translated ones

App Context Configuration

The app context configuration helps Claude provide more accurate and contextually appropriate translations. The configuration consists of:

• App description and purpose
• Key terminology and definitions
• Style guide and tone preferences
• Target audience information

An example configuration is provided in app_context.example.yaml. To use it:

1. Copy app_context.example.yaml to app_context.yaml
2. Edit app_context.yaml with your app's specific details
3. Keep sensitive app information private - app_context.yaml is gitignored by default

Example configuration structure:

preserve_names:
  app_names: ["Your App Name"]
  product_models: ["Product Model Names"]

app_description: |
  Your app's description and purpose...

terminology:
  - term: "Important Term"
    description: "Term definition"
    note: "Usage notes"

style_guide:
  tone: "Your preferred tone"
  formality: "Desired formality level"
  technical_level: "Target technical expertise"
  key_points:
    - "Translation guidelines..."

This context helps Claude understand your app's domain and provide translations that match your desired style and terminology.

Translation Prompts

The tool uses customizable prompts to guide Claude's translation process. These prompts are stored in YAML format:

1. Copy prompts.example.yaml to prompts.yaml
2. Customize the prompts as needed

The prompts file contains two main sections:

• system_prompt: Sets Claude's role and response format
• translation_prompt: Guides the actual translation process

Both prompts support variables that are automatically filled during translation:

• {target_lang}: Target language code
• {app_context}: Content from your app context file
• {num_texts}: Number of strings to translate
• {numbered_texts}: The actual strings to translate

Your custom prompts in prompts.yaml are gitignored by default to protect any app-specific information.

Helper Scripts

Export Localizations

You can use the provided script to export XLIFF files from your Xcode project:

1. Copy the example script:

   cp scripts/export_localizations.example.sh scripts/export_localizations.sh

2. Edit the script to set your paths and languages:

   PROJECT_PATH="path/to/your/Project.xcodeproj"  # Your Xcode project file
   EXPORT_DIR="path/to/export/folder"             # Where to save .xcloc files
   LANGUAGES="fr es ja zh-Hans zh-Hant"           # Languages to export (leave empty for all)

3. Make the script executable:

   chmod +x scripts/export_localizations.sh

4. Run the script:

   ./scripts/export_localizations.sh

The script will:

• Create the export directory if it doesn't exist
• Export XLIFF files for specified languages (or all languages if none specified)
• Show the status of each export operation

Import Localizations

After translating your XLIFF files, you can use the provided script to import them back into your Xcode project:

1. Copy the example script:

   cp scripts/import_localizations.example.sh scripts/import_localizations.sh

2. Edit the script to set your paths:

   LOCALIZATIONS_DIR="path/to/your/localizations/folder"  # Where your .xcloc files are
   PROJECT_PATH="path/to/your/Project.xcodeproj"         # Your Xcode project file

3. Make the script executable:

   chmod +x scripts/import_localizations.sh

4. Run the script:

   ./scripts/import_localizations.sh

The script will:

• Find all .xcloc files in the specified directory (excluding en.xcloc)
• Import each localization into your Xcode project
• Show the status of each import operation