string-catalog

A CLI tool for translating Xcode string catalogs.

Apps using this tool:

• ByePhotos: Find similar photos and compress large videos to free up space on your iPhone and iCloud.
• ParkClock: Parking Timer & Reminder.
• OptiClean: Removes unwanted objects from photos using AI, run model fully on device.

Installation

Install this tool using pip:

pip install string-catalog

Usage

For help, run:

string-catalog --help

Translate a single xcstrings file or all xcstrings files in a directory

export OPENROUTER_API_KEY=sk-or-v1-xxxxx
string-catalog xcstrings translate /path_or_dir/to/xcstrings_file \
--model anthropic/claude-3.5-sonnet \
--lang ru \
--lang zh-Hant

Translate a single xcstrings file and all supported languages using deepseek-v3 API

string-catalog xcstrings translate /path_or_dir/to/xcstrings_file \
--base-url https://api.deepseek.com \
--api-key sk-xxxx --model deepseek-chat --lang all

• All API call results are cached in the .translation_cache/ directory and will be used first for subsequent calls.

The translation results have a default state of needs_review. If you need to update them to translated (for example, after reviewing all translations in Xcode and wanting to avoid manually clicking "Mark as Reviewed" for each one), you can use the following command:

string-catalog xcstrings update-state /path_or_dir/to/xcstrings_file \
--old needs_review \
--new translated

App Store Connect Automation

Generate What's New JSON file from xcstrings file:

string-catalog xcstrings generate-whats-new /path_to/WhatsNewLocalizable.xcstrings \
--key v1.1_feature1 \
--key v1.1_feature2

Here is the generated JSON file:

{
  "it": "Nuova funzione 1: Titolo\nNuova funzione 2: Titolo",
  "pt": "Nova funcionalidade 1: Título\nNova funcionalidade 2: Título",
  "ja": "新機能1: タイトル\n新機能2: タイトル",
  "zh-Hans": "新功能1: 标题\n新功能2: 标题"
}

Creating ISSUER_ID, KEY_ID, and KEY_FILE for App Store Connect API, then update Whats New using the following command:

export ASC_ISSUER_ID=xxxx
export ASC_KEY_ID=xxxx
export ASC_KEY_FILE=xxxx.p8

string-catalog appstore update-whats-new \
--bundle-id com.xxx.xxx \
--version 1.0.0 \
--json-path whats_new.json \
--platform IOS

Development

To contribute to this tool, first checkout the code. Then create a new virtual environment:

uv run string-catalog --help

Test:

uv run pytest

Acknowledgments

This project is inspired by swift-translate.