Initial commit
This commit is contained in:
Zhongwei Li
357
skills/jta/SKILL.md
Normal file
357
skills/jta/SKILL.md
Normal file
@@ -0,0 +1,357 @@
|
||||
---
|
||||
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
|
||||
|
||||
```bash
|
||||
# Check if jta exists
|
||||
if ! command -v jta &> /dev/null; then
|
||||
echo "jta not found, will install"
|
||||
fi
|
||||
```
|
||||
|
||||
### Step 2: Install jta if needed
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```bash
|
||||
# User: "Translate my en.json to Chinese and Japanese"
|
||||
jta locales/en.json --to zh,ja -y $PROVIDER_FLAG
|
||||
```
|
||||
|
||||
### Pattern 2: Update existing translations
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# User: "Only translate the settings and user sections"
|
||||
jta en.json --to zh --keys "settings.**,user.**" $PROVIDER_FLAG
|
||||
```
|
||||
|
||||
### Pattern 4: High-quality translation
|
||||
```bash
|
||||
# User: "Use the best model for highest quality"
|
||||
jta en.json --to zh --provider anthropic --model claude-sonnet-4-5
|
||||
```
|
||||
|
||||
### Pattern 5: RTL languages
|
||||
```bash
|
||||
# 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"
|
||||
```bash
|
||||
# Reduce batch size and concurrency
|
||||
jta en.json --to zh --batch-size 10 --concurrency 1
|
||||
```
|
||||
|
||||
### Error: "Invalid JSON"
|
||||
```bash
|
||||
# Validate source file
|
||||
jq . source.json
|
||||
```
|
||||
|
||||
### Error: Translation quality issues
|
||||
1. Try a better model:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
# 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/](examples/) directory for detailed, step-by-step use cases.
|
||||
Reference in New Issue
Block a user