Xcstrings Crud

🚀 xcstrings-crud

A CLI tool and MCP server for performing CRUD operations on xcstrings (String Catalog) files. This tool addresses the issue of large xcstrings files, which can contain thousands of localization keys across multiple languages, resulting in massive JSON files. When AI assistants like Claude Code read these files directly, they consume a significant amount of tokens, potentially exceeding context limits or rapidly depleting token budgets.

✨ Features

• Token-efficient: Offers targeted CRUD operations to minimize token usage.
• Query targeted data: Fetch specific keys or languages instead of loading the entire file.
• Incremental updates: Add or update individual translations without reading the full content.
• Quick stats: Get coverage and progress summaries without parsing all entries.

📦 Installation

Using Mise

mise use -g ubi:Ryu0118/xcstrings-crud

Using nest (mtj0928/nest)

nest install Ryu0118/xcstrings-crud

Build from source

git clone https://github.com/Ryu0118/xcstrings-crud.git
cd xcstrings-crud
swift build -c release

The binary will be located at .build/release/xcstrings-crud.

🚀 Quick Start

MCP Server

The MCP server is available as a subcommand:

xcstrings-crud mcp

Configuration

Add the following to your Claude Code MCP settings:

{
  "mcpServers": {
    "xcstrings-crud": {
      "command": "xcstrings-crud",
      "args": ["mcp"]
    }
  }
}

Available Tools

💻 Usage Examples

CLI Usage

Create Operations

# Create a new xcstrings file
xcstrings-crud create path/to/Localizable.xcstrings

# Create with specific source language
xcstrings-crud create path/to/Localizable.xcstrings --source-language ja

# Overwrite existing file
xcstrings-crud create path/to/Localizable.xcstrings --overwrite

Read Operations

# List all keys
xcstrings-crud list keys --file path/to/Localizable.xcstrings

# List languages
xcstrings-crud list languages --file path/to/Localizable.xcstrings

# List untranslated keys for a language
xcstrings-crud list untranslated --file path/to/Localizable.xcstrings --lang ja

# List stale keys (potentially unused)
xcstrings-crud list stale --file path/to/Localizable.xcstrings

# List stale keys across multiple files
xcstrings-crud batch stale -f file1.xcstrings file2.xcstrings file3.xcstrings

# Get source language
xcstrings-crud get source-language --file path/to/Localizable.xcstrings

# Get translations for a key
xcstrings-crud get key "Hello" --file path/to/Localizable.xcstrings
xcstrings-crud get key "Hello" --file path/to/Localizable.xcstrings --lang ja

# Check if key exists
xcstrings-crud check key "Hello" --file path/to/Localizable.xcstrings

# Check key coverage
xcstrings-crud check coverage "Hello" --file path/to/Localizable.xcstrings

# Get overall statistics
xcstrings-crud stats coverage --file path/to/Localizable.xcstrings

# Get progress for a language
xcstrings-crud stats progress --file path/to/Localizable.xcstrings --lang ja

# Get batch coverage for multiple files
xcstrings-crud stats batch-coverage -f file1.xcstrings file2.xcstrings file3.xcstrings

Update Operations

# Add translation (single language)
xcstrings-crud add key "Hello" --file path/to/Localizable.xcstrings --lang ja --value "こんにちは"

# Add translation (multiple languages)
xcstrings-crud add key "Hello" --file path/to/Localizable.xcstrings -t ja:こんにちは en:Hello

# Update translation (single language)
xcstrings-crud update key "Hello" --file path/to/Localizable.xcstrings --lang ja --value "こんにちは！"

# Update translations (multiple languages)
xcstrings-crud update key "Hello" --file path/to/Localizable.xcstrings -t ja:こんにちは en:Hello de:Hallo

# Rename key
xcstrings-crud rename key "Hello" --file path/to/Localizable.xcstrings --to "Greeting"

Delete Operations

# Delete entire key
xcstrings-crud delete key "Hello" --file path/to/Localizable.xcstrings

# Delete translation for specific language only
xcstrings-crud delete key "Hello" --file path/to/Localizable.xcstrings -l ja

# Delete translations for multiple languages
xcstrings-crud delete key "Hello" --file path/to/Localizable.xcstrings -l ja en fr

Batch Operations

# List stale keys across multiple files
xcstrings-crud batch stale -f file1.xcstrings file2.xcstrings file3.xcstrings

# Check if multiple keys exist
xcstrings-crud batch check --file path/to/Localizable.xcstrings -k Hello Goodbye Welcome

# Check with specific language
xcstrings-crud batch check --file path/to/Localizable.xcstrings -k Hello Goodbye -l ja

# Add translations for multiple keys at once
xcstrings-crud batch add --file path/to/Localizable.xcstrings \
  -e "Hello=ja:こんにちは,en:Hello" \
  -e "Goodbye=ja:さようなら,en:Goodbye"

# Add with overwrite (replace existing translations)
xcstrings-crud batch add --file path/to/Localizable.xcstrings --overwrite \
  -e "Hello=ja:こんにちは,en:Hello"

# Update translations for multiple keys at once
xcstrings-crud batch update --file path/to/Localizable.xcstrings \
  -e "Hello=ja:こんにちは！,en:Hello!" \
  -e "Goodbye=ja:さようなら！"

Common Options

• --file <path>: xcstrings file path (required)
• --pretty: Pretty-printed JSON output

🔧 Technical Details

• System Requirements: macOS 13+ and Swift 6.0+

📄 License

This project is licensed under the MIT license.