ckanner/jta

Jta Translation

AI-powered JSON internationalization file translator with Agentic reflection mechanism.

When to Use This Skill

• User asks to translate JSON i18n/locale files
• User mentions "internationalization", "i18n", "l10n", or "locale"
• User wants to add new languages to their project
• User needs to update existing translations
• User mentions specific languages like "translate to Chinese/Japanese/Korean"

Core Capabilities

1. Agentic Translation: AI translates, evaluates, and improves its own work (3x API calls per batch)
2. Smart Terminology: Automatically detects and maintains consistent terms (brand names, technical terms)
3. Format Protection: Preserves {variables}, {{placeholders}}, HTML tags, URLs, Markdown
4. Incremental Mode: Only translates new/changed content (saves 80-90% API cost on updates)
5. 27 Languages: Including RTL languages (Arabic, Hebrew, Persian, Urdu)

Instructions

Step 1: Check if jta is installed

# Check if jta exists
if ! command -v jta &> /dev/null; then
  echo "jta not found, will install"
fi

Step 2: Install jta if needed

# Detect OS and install jta
OS="$(uname -s)"
ARCH="$(uname -m)"

if [[ "$OS" == "Darwin"* ]]; then
  # macOS - try Homebrew first
  if command -v brew &> /dev/null; then
    brew tap hikanner/jta
    brew install jta
  else
    # Download binary
    if [[ "$ARCH" == "arm64" ]]; then
      curl -L https://github.com/hikanner/jta/releases/latest/download/jta-darwin-arm64 -o jta
    else
      curl -L https://github.com/hikanner/jta/releases/latest/download/jta-darwin-amd64 -o jta
    fi
    chmod +x jta
    sudo mv jta /usr/local/bin/
  fi
elif [[ "$OS" == "Linux"* ]]; then
  # Linux
  curl -L https://github.com/hikanner/jta/releases/latest/download/jta-linux-amd64 -o jta
  chmod +x jta
  sudo mv jta /usr/local/bin/
fi

# Verify installation
jta --version

Step 3: Check for API key and set provider

Jta requires an AI provider API key. Check in this order and set the provider flag:

# Detect API key and set provider flag
if [[ -n "$ANTHROPIC_API_KEY" ]]; then
  echo "✓ Anthropic API key found"
  PROVIDER_FLAG="--provider anthropic"
elif [[ -n "$GEMINI_API_KEY" ]]; then
  echo "✓ Gemini API key found"
  PROVIDER_FLAG="--provider gemini"
elif [[ -n "$OPENAI_API_KEY" ]]; then
  echo "✓ OpenAI API key found"
  PROVIDER_FLAG=""  # OpenAI is default, no flag needed
else
  echo "✗ No API key found. Please set one of:"
  echo "  export OPENAI_API_KEY=sk-..."
  echo "  export ANTHROPIC_API_KEY=sk-ant-..."
  echo "  export GEMINI_API_KEY=..."
  exit 1
fi

Important: Save the PROVIDER_FLAG value to use in translation commands.

Step 4: Identify source file

# Find JSON files in common i18n/locale directories
find . -type f -name "*.json" \
  \( -path "*/locales/*" -o \
     -path "*/locale/*" -o \
     -path "*/i18n/*" -o \
     -path "*/lang/*" -o \
     -path "*/translations/*" \) \
  | head -20

Ask user to confirm which file to translate if multiple found.

Step 5: Determine translation requirements

Ask user (if not specified in their request):

• Target languages (e.g., "zh,ja,ko")
• Whether to use incremental mode (recommended for updates)
• Output location preference

Step 6: Execute translation

Always use $PROVIDER_FLAG from Step 3 to ensure the correct AI provider is used:

# Basic translation with detected provider
jta <source-file> --to <target-langs> $PROVIDER_FLAG

# Examples:
# Single language
jta en.json --to zh $PROVIDER_FLAG

# Multiple languages
jta en.json --to zh,ja,ko $PROVIDER_FLAG

# Incremental mode (for updates)
jta en.json --to zh --incremental $PROVIDER_FLAG

# With custom output
jta en.json --to zh --output ./locales/zh.json $PROVIDER_FLAG

# Non-interactive mode (for multiple languages)
jta en.json --to zh,ja,ko,es,fr -y $PROVIDER_FLAG

# Override with specific model for quality
jta en.json --to zh --provider anthropic --model claude-sonnet-4-5

# Translate specific keys only
jta en.json --to zh --keys "settings.*,user.*" $PROVIDER_FLAG

# Exclude certain keys
jta en.json --to zh --exclude-keys "admin.*,internal.*" $PROVIDER_FLAG

Step 7: Verify results

After translation completes:

# Check output files exist
ls -lh <output-files>

# Validate JSON structure
for file in <output-files>; do
  if jq empty "$file" 2>/dev/null; then
    echo "✓ $file is valid JSON"
  else
    echo "✗ $file has invalid JSON"
  fi
done

Step 8: Report to user

Show the user:

• Translation statistics (total items, success rate, API calls, duration)
• Location of output files
• Any errors or warnings
• Cost implications if significant (e.g., "Used 15 API calls, estimated $0.30")

Terminology Management

Jta automatically creates a .jta/ directory to store terminology:

.jta/
├── terminology.json       # Source language terms (preserve + consistent)
├── terminology.zh.json    # Chinese translations
├── terminology.ja.json    # Japanese translations
└── terminology.ko.json    # Korean translations

terminology.json structure:

{
  "version": "1.0",
  "sourceLanguage": "en",
  "preserveTerms": ["API", "OAuth", "GitHub"],
  "consistentTerms": ["credits", "workspace", "prompt"]
}

Users can manually edit these files for custom terminology.

Common Patterns

Note: Always include $PROVIDER_FLAG (from Step 3) in your commands.

Pattern 1: First-time translation

# User: "Translate my en.json to Chinese and Japanese"
jta locales/en.json --to zh,ja -y $PROVIDER_FLAG

Pattern 2: Update existing translations

# User: "I added new keys to en.json, update the translations"
jta locales/en.json --to zh,ja --incremental -y $PROVIDER_FLAG

Pattern 3: Translate specific sections

# User: "Only translate the settings and user sections"
jta en.json --to zh --keys "settings.**,user.**" $PROVIDER_FLAG

Pattern 4: High-quality translation

# User: "Use the best model for highest quality"
jta en.json --to zh --provider anthropic --model claude-sonnet-4-5

Pattern 5: RTL languages

# User: "Translate to Arabic and Hebrew"
jta en.json --to ar,he -y $PROVIDER_FLAG
# Jta automatically handles bidirectional text markers

Error Handling

Error: "jta: command not found"

• Run the installation script from Step 2
• Verify with jta --version

Error: "API key not set"

Prompt user:

Jta requires an AI provider API key. Please set one of:

For OpenAI (recommended):
  export OPENAI_API_KEY=sk-...
  Get key at: https://platform.openai.com/api-keys

For Anthropic:
  export ANTHROPIC_API_KEY=sk-ant-...
  Get key at: https://console.anthropic.com/

For Google Gemini:
  export GEMINI_API_KEY=...
  Get key at: https://aistudio.google.com/app/apikey

Error: "Rate limit exceeded"

# Reduce batch size and concurrency
jta en.json --to zh --batch-size 10 --concurrency 1

Error: "Invalid JSON"

# Validate source file
jq . source.json

Error: Translation quality issues

1. Try a better model:

   jta en.json --to zh --provider anthropic --model claude-sonnet-4-5
   

2. Check terminology files in .jta/ and edit if needed

3. Use verbose mode to debug:

   jta en.json --to zh --verbose
   

Performance Tips

• Small files (<100 keys): Use default settings
• Large files (>500 keys): Use --batch-size 10 --concurrency 2
• Frequent updates: Always use --incremental to save cost
• Quality priority: Use --provider anthropic --model claude-sonnet-4-5
• Speed priority: Use --provider openai --model gpt-3.5-turbo (if available)
• Cost priority: Use incremental mode + larger batch sizes

Supported Languages

27 languages with full support:

Left-to-Right (LTR):

• European: en, es, fr, de, it, pt, ru, nl, pl, tr
• Asian: zh, zh-TW, ja, ko, th, vi, id, ms, hi, bn, si, ne, my

Right-to-Left (RTL):

• Middle Eastern: ar, fa, he, ur

View all supported languages:

jta --list-languages

Output Format

Jta produces:

1. Translated JSON files: Same structure as source, with translations
2. Statistics: Printed to console
3. Terminology files: In .jta/ directory for consistency

Always inform the user of:

• Number of items translated
• Success/failure count
• Output file locations
• Any errors or warnings
• API usage and estimated cost (if significant)

Advanced Options

Note: Remember to include $PROVIDER_FLAG in your commands.

# Skip terminology detection (use existing)
jta en.json --to zh --skip-terminology $PROVIDER_FLAG

# Disable terminology management completely
jta en.json --to zh --no-terminology $PROVIDER_FLAG

# Re-detect terminology (when source language changes)
jta en.json --to zh --redetect-terms $PROVIDER_FLAG

# Custom terminology directory (for shared terms)
jta en.json --to zh --terminology-dir ../shared-terms/ $PROVIDER_FLAG

# Specify source language explicitly
jta myfile.json --source-lang en --to zh $PROVIDER_FLAG

# Custom batch size and concurrency
jta en.json --to zh --batch-size 20 --concurrency 3 $PROVIDER_FLAG

# Verbose output for debugging
jta en.json --to zh --verbose $PROVIDER_FLAG

Examples

See examples/ directory for detailed, step-by-step use cases.