jta

name	jta
description	Translate JSON i18n files to multiple languages with AI-powered quality optimization. Use when user mentions translating JSON, i18n files, internationalization, locale files, or needs to convert language files to other languages.
version	1.0.0
license	Complete terms in LICENSE.txt
allowed-tools	Read, Write, Bash, Glob

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.