Jta - JSON Translation Agent

AI-powered Agentic JSON Translation tool with intelligent quality optimization

Jta is a production-ready command-line tool that uses AI to translate JSON internationalization files with exceptional accuracy and consistency. It features an agentic reflection mechanism where AI translates, evaluates, and refines its own work, along with automatic terminology detection and robust format preservation for production-grade translations.

📑 Table of Contents

🔥 Agent Skills
Key Features
Installation
Quick Start
Documentation
Supported AI Providers
Supported Languages
Architecture
Examples
Configuration
Troubleshooting
FAQ
Contributing
License
Acknowledgments
Support

🔥 Agent Skills

Jta can be used as an Agent Skill to enable AI agents like Claude to automatically translate JSON i18n files.

Quick Start with Skills

For Individual Users:

# Copy the skill to your Claude skills directory
cp -r skills/jta ~/.claude/skills/

# Or create a symbolic link (recommended for development)
ln -s $(pwd)/skills/jta ~/.claude/skills/jta

For Project Teams:

# The skill is already in the repository at skills/jta
# When team members clone the repo, they can use it immediately
cp -r skills/jta .claude/skills/

Using the Skill:

Once installed, simply ask your AI agent:

"Translate my en.json to Chinese, Japanese, and Korean"

The agent will automatically:

Install Jta if needed
Verify API key configuration
Execute translation with optimal settings
Show results and statistics

What's Included

The skills/jta directory contains:

SKILL.md - Complete skill definition and instructions for AI agents
examples/ - Step-by-step use cases:
- Basic translation workflow
- Incremental translation mode
- CI/CD integration
scripts/ - Installation helpers

Learn More

See skills/README.md for complete documentation on using Jta as an Agent Skill.

✨ Key Features

🤖 Agentic Translation with Self-Optimization

Agentic Reflection Mechanism: AI acts as its own quality reviewer through a two-step process - first translating, then critically evaluating and refining its own work
Multi-Dimensional Quality Evaluation: The AI examines translations across 4 key dimensions: accuracy (no mistranslations), fluency (natural grammar), style (cultural appropriateness), and terminology (consistency)
Self-Generated Improvements: Rather than relying on predefined rules, the AI generates specific, contextual suggestions and applies them to produce better translations
Iterative Refinement: Each translation goes through translate → reflect → improve cycles, ensuring higher quality output
Trade-off: 3x API calls per batch for significantly improved translation quality

📚 Intelligent Terminology Management

Automatic Detection: Uses LLM to identify important terms in your content
Preserve Terms: Brand names, technical terms that should never be translated
Consistent Terms: Domain-specific terms translated uniformly across all content
Editable Dictionary: Saved to .jta-terminology.json for manual refinement

🔒 Robust Format Protection

Automatically preserves:

Placeholders: {variable}, {{count}}, %s, %(name)d
HTML Tags: <b>, <span class="highlight">, <a href="...">
URLs: https://example.com, http://api.example.com/v1
Markdown: **bold**, *italic*, [link](url)

⚡ Smart Incremental Translation

Only translates new or modified content
Preserves existing high-quality translations
Automatically removes obsolete keys
Saves time and API costs (typically 80-90% reduction on updates)

🎯 Flexible Key Filtering

Glob Patterns: settings.*, user.**, *.title
Precise Control: Include or exclude specific sections
Recursive Wildcards: Translate entire subsections with **

🌍 RTL Language Support

Proper bidirectional text handling for Arabic, Hebrew, Persian, Urdu
Automatic direction markers for LTR content in RTL context
Smart punctuation conversion for Arabic-script languages

🚀 Production-Ready Performance

Batch processing with configurable concurrency
Retry logic with exponential backoff
Graceful error handling and recovery
Progress indicators and detailed statistics

🎨 Multi-Provider Support

OpenAI: All models including GPT-5, GPT-5 mini, GPT-5 nano, GPT-4o, etc.
Anthropic: All Claude models including Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1, etc.
Gemini: All Gemini models including Gemini 2.5 Flash, Gemini 2.5 Pro, etc.

📦 Installation

Homebrew (macOS/Linux) - Recommended

The easiest way to install Jta on macOS or Linux:

# Add the tap
brew tap hikanner/jta

# Install Jta
brew install jta

# Verify installation
jta --version

Upgrade:

brew upgrade jta

Uninstall:

brew uninstall jta
brew untap hikanner/jta

Download Binary

Download the latest release for your platform from GitHub Releases:

macOS: jta-darwin-amd64 or jta-darwin-arm64 (Apple Silicon)
Linux: jta-linux-amd64 or jta-linux-arm64
Windows: jta-windows-amd64.exe

# macOS/Linux example
curl -L https://github.com/hikanner/jta/releases/latest/download/jta-darwin-arm64 -o jta
chmod +x jta
sudo mv jta /usr/local/bin/

Using Go Install

go install github.com/hikanner/jta/cmd/jta@latest

From Source

git clone https://github.com/hikanner/jta.git
cd jta
go build -o jta cmd/jta/main.go

🚀 Quick Start

Installation

# Install via Homebrew (recommended for macOS/Linux)
brew tap hikanner/jta
brew install jta

# Or download binary from GitHub Releases
# See Installation section for details

View Supported Languages

# List all supported languages
jta --list-languages

Basic Usage

# Translate to a single language
jta en.json --to zh

# Translate to multiple languages
jta en.json --to zh,ja,ko

# Specify output directory
jta en.json --to zh --output ./locales/

With AI Provider Configuration

# Using environment variables (recommended)
export OPENAI_API_KEY=sk-...
jta en.json --to zh

# Or specify directly
jta en.json --to zh --provider anthropic --api-key sk-ant-...

Advanced Usage

# Incremental translation (only translate new/modified content)
jta en.json --to zh --incremental

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

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

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

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

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

# Non-interactive mode (for CI/CD)
jta en.json --to zh,ja,ko -y

# CI/CD with incremental translation
jta en.json --to zh --incremental -y

📖 Documentation

Terminology Management

Jta automatically detects important terminology in your source file and ensures consistent translation:

Preserve Terms: Brand names, technical terms that should never be translated (e.g., API, OAuth, GitHub)
Consistent Terms: Domain terms that must be translated uniformly (e.g., credits, workspace, premium)

File Structure:

Terminology is stored in a dedicated directory (default .jta/):

.jta/
├── terminology.json       # Term definitions (source language)
├── terminology.zh.json    # Chinese translations
├── terminology.ja.json    # Japanese translations
└── terminology.ko.json    # Korean translations

terminology.json (source language terms):

{
  "version": "1.0",
  "sourceLanguage": "en",
  "detectedAt": "2025-01-26T10:30:00Z",
  "preserveTerms": ["API", "OAuth", "JSON"],
  "consistentTerms": ["credits", "workspace", "prompt"]
}

terminology.zh.json (translations):

{
  "version": "1.0",
  "sourceLanguage": "en",
  "targetLanguage": "zh",
  "translatedAt": "2025-01-26T10:31:00Z",
  "translations": {
    "credits": "积分",
    "workspace": "工作空间",
    "prompt": "提示词"
  }
}

Workflow:

First run: Detects terms → saves to terminology.json → translates to target language
Subsequent runs: Loads existing terms → translates missing terms only
New language: Uses existing terminology.json → creates terminology.{lang}.json

Custom Terminology Directory:

# Use a shared terminology directory
jta en.json --to zh --terminology-dir ../shared-terms/

# Multiple projects can share the same terminology
jta projectA/en.js

Jta

Install / Use

README