zhongwei/gh-hikanner-agent-skills-jta
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:45:38 +08:00
commit 31058165d8
10 changed files with 1808 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
skills/jta/examples/basic-translation.md Normal file
View File

@@ -0,0 +1,265 @@
# Example: Basic Translation
This example demonstrates the most common use case: translating a JSON i18n file to multiple languages.
## Scenario
User has `locales/en.json` containing English translations and wants to add Chinese, Japanese, and Korean support.
## User Request
> "Translate my en.json to Chinese, Japanese, and Korean"
## Claude's Workflow
### Step 1: Understand the Request
Claude recognizes:
- **Task**: Translation
- **Source file**: en.json (implied to be in locales/)
- **Target languages**: Chinese (zh), Japanese (ja), Korean (ko)
- **Mode**: First-time translation (full, not incremental)
### Step 2: Locate the Source File
```bash
# Find JSON files in locale directories
find . -type f -name "en.json" \( -path "*/locales/*" -o -path "*/locale/*" -o -path "*/i18n/*" \)
```
Output:
```
./locales/en.json
```
### Step 3: Check Environment
```bash
# Verify jta is installed
jta --version
```
If not installed:
```bash
# Install via Homebrew (macOS)
brew tap hikanner/jta && brew install jta
```
Check API key:
```bash
# Check if API key exists
if [[ -n "$OPENAI_API_KEY" ]]; then
echo "✓ API key found"
fi
```
### Step 4: Preview Source File
```bash
# Show file structure
jq '.' locales/en.json | head -20
```
Output:
```json
{
"app": {
"name": "My App",
"welcome": "Welcome to {appName}!"
},
"settings": {
"title": "Settings",
"language": "Language"
}
}
```
### Step 5: Execute Translation
```bash
# Translate to Chinese, Japanese, and Korean
jta locales/en.json --to zh,ja,ko -y
```
**What happens:**
1. **Terminology Detection**: Jta analyzes content and detects important terms
2. **Batch Processing**: Splits into batches (default 20 keys per batch)
3. **Translation**: Sends each batch to AI provider
4. **Agentic Reflection**: AI evaluates and improves translations
5. **Output**: Creates zh.json, ja.json, ko.json
### Step 6: Monitor Progress
Console output:
```
📄 Loading source file...
✓ Source file loaded (100 keys)
📚 Loading terminology...
🔍 Detecting terminology...
✓ Detected 8 terms (3 preserve, 5 consistent)
🤖 Translating to Chinese (zh)...
Processing ━━━━━━━━━━━━━━━━━━━━ 100% (100/100)
✓ Chinese translation completed
🤖 Translating to Japanese (ja)...
Processing ━━━━━━━━━━━━━━━━━━━━ 100% (100/100)
✓ Japanese translation completed
🤖 Translating to Korean (ko)...
Processing ━━━━━━━━━━━━━━━━━━━━ 100% (100/100)
✓ Korean translation completed
💾 Saving translations...
✓ Saved to locales/zh.json
✓ Saved to locales/ja.json
✓ Saved to locales/ko.json
```
### Step 7: Verify Results
```bash
# Check created files
ls -lh locales/*.json
```
Output:
```
-rw-r--r-- 1 user staff 2.3K en.json
-rw-r--r-- 1 user staff 2.8K zh.json
-rw-r--r-- 1 user staff 3.1K ja.json
-rw-r--r-- 1 user staff 2.9K ko.json
```
Validate JSON structure:
```bash
for file in locales/{zh,ja,ko}.json; do
if jq empty "$file" 2>/dev/null; then
echo "✓ $file is valid JSON"
fi
done
```
### Step 8: Show Statistics
```
📊 Translation Statistics
Chinese (zh):
Total items: 100
Success: 100
Failed: 0
Duration: 45s
API calls: 15 (5 translate + 5 reflect + 5 improve)
Japanese (ja):
Total items: 100
Success: 100
Failed: 0
Duration: 48s
API calls: 15
Korean (ko):
Total items: 100
Success: 100
Failed: 0
Duration: 43s
API calls: 15
Total Duration: 2m 16s
Total API calls: 45
Estimated cost: ~$0.90 (using GPT-4o)
Terminology saved to .jta/ directory for future consistency.
```
## Claude's Response to User
```
✅ Translation completed successfully!
I've translated your en.json to Chinese, Japanese, and Korean.
**Files created:**
- `locales/zh.json` (Chinese Simplified)
- `locales/ja.json` (Japanese)
- `locales/ko.json` (Korean)
**Statistics:**
- Total items: 100 per language
- Success rate: 100%
- Duration: 2 minutes 16 seconds
- API calls: 45 total (15 per language with Agentic reflection)
- Estimated cost: ~$0.90
**Terminology management:**
Jta detected 8 important terms and saved them to `.jta/` directory:
- Preserve terms (never translate): API, OAuth, JSON
- Consistent terms (translate uniformly): credits, workspace, settings, profile, template
All placeholders ({appName}), HTML tags, and URLs have been preserved in the translations.
Would you like me to show you a sample of the translations or make any adjustments?
```
## Sample Translations
### English (source)
```json
{
"app": {
"welcome": "Welcome to {appName}!",
"description": "Manage your <b>workspace</b> settings"
},
"user": {
"credits": "You have {count} credits remaining"
}
}
```
### Chinese (zh.json)
```json
{
"app": {
"welcome": "欢迎来到 {appName}!",
"description": "管理您的<b>工作空间</b>设置"
},
"user": {
"credits": "您还有 {count} 积分"
}
}
```
### Japanese (ja.json)
```json
{
"app": {
"welcome": "{appName}へようこそ!",
"description": "<b>ワークスペース</b>の設定を管理"
},
"user": {
"credits": "残り {count} クレジットがあります"
}
}
```
### Korean (ko.json)
```json
{
"app": {
"welcome": "{appName}에 오신 것을 환영합니다!",
"description": "<b>워크스페이스</b> 설정 관리"
},
"user": {
"credits": "{count}개의 크레딧이 남아 있습니다"
}
}
```
## Notes
- All placeholders (`{appName}`, `{count}`) preserved
- HTML tags (`<b>`) preserved
- Terminology consistency maintained ("workspace" → "工作空间", "ワークスペース", "워크스페이스")
- Agentic reflection ensured natural, fluent translations

446
skills/jta/examples/ci-cd-integration.md Normal file
View File

@@ -0,0 +1,446 @@
# Example: CI/CD Integration
This example demonstrates how to automatically translate i18n files in a CI/CD pipeline whenever the source file changes.
## Scenario
Team maintains a multilingual web application. When developers update `en.json`, the CI/CD pipeline should automatically:
1. Detect the change
2. Translate to all target languages
3. Commit the translations back to the repository
## User Request
> "Set up automatic translation in our GitHub Actions when en.json changes"
## Claude's Workflow
### Step 1: Understand Requirements
Claude recognizes:
- **Platform**: GitHub Actions (CI/CD)
- **Trigger**: Changes to en.json
- **Target languages**: Multiple (need to confirm with user)
- **Mode**: Incremental (to save costs)
### Step 2: Confirm Configuration
Claude asks:
```
To set up automatic translation, I need to know:
1. What languages do you want to translate to?
2. Where is your source file? (e.g., locales/en.json)
3. Do you have an OPENAI_API_KEY secret set in GitHub?
```
User responds:
> "Translate to Chinese, Japanese, Korean, Spanish, and French. Source is `locales/en.json`. Yes, we have OPENAI_API_KEY in GitHub secrets."
### Step 3: Create GitHub Actions Workflow
```bash
# Create workflow directory if it doesn't exist
mkdir -p .github/workflows
```
Create workflow file:
```yaml
# .github/workflows/translate-i18n.yml
name: Auto-translate i18n files
on:
push:
branches:
- main
- develop
paths:
- 'locales/en.json'
jobs:
translate:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for proper git operations
- name: Install Jta
run: |
curl -L https://github.com/hikanner/jta/releases/latest/download/jta-linux-amd64 -o jta
chmod +x jta
sudo mv jta /usr/local/bin/
jta --version
- name: Translate to all languages
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
# Use incremental mode to only translate changes
# Non-interactive mode (-y) for CI/CD
jta locales/en.json --to zh,ja,ko,es,fr --incremental -y
- name: Check for translation changes
id: check_changes
run: |
# Check if any translation files were modified
if [[ -n $(git status -s locales/*.json) ]]; then
echo "changes=true" >> $GITHUB_OUTPUT
echo "Translation files were updated"
else
echo "changes=false" >> $GITHUB_OUTPUT
echo "No translation changes"
fi
- name: Commit and push translations
if: steps.check_changes.outputs.changes == 'true'
run: |
git config user.name "Translation Bot"
git config user.email "bot@example.com"
git add locales/*.json
git add .jta/ # Include terminology updates
git commit -m "chore: auto-translate i18n files
- Updated translations for Chinese, Japanese, Korean, Spanish, French
- Triggered by changes to en.json
- Translated using Jta with incremental mode
🤖 Generated automatically by GitHub Actions"
git push
- name: Comment on commit (optional)
if: steps.check_changes.outputs.changes == 'true'
uses: actions/github-script@v7
with:
script: |
github.rest.repos.createCommitComment({
owner: context.repo.owner,
repo: context.repo.repo,
commit_sha: context.sha,
body: '✅ Translations updated automatically by Jta'
})
```
### Step 4: Set Up GitHub Secret
Create instructions for the user:
```bash
# In GitHub repository settings:
# 1. Go to Settings → Secrets and variables → Actions
# 2. Click "New repository secret"
# 3. Name: OPENAI_API_KEY
# 4. Value: your OpenAI API key (sk-...)
# 5. Click "Add secret"
```
### Step 5: Create Pre-commit Hook (Optional)
For local development, create a pre-commit hook:
```bash
# .git/hooks/pre-commit
#!/bin/bash
# Check if en.json was modified
if git diff --cached --name-only | grep -q "locales/en.json"; then
echo "🔍 en.json modified, checking translations..."
# Check if API key exists
if [[ -z "$OPENAI_API_KEY" ]]; then
echo "⚠️ Warning: OPENAI_API_KEY not set. Translations will be updated in CI."
else
echo "🤖 Running incremental translation..."
jta locales/en.json --to zh,ja,ko,es,fr --incremental -y
# Stage updated translations
git add locales/*.json .jta/
echo "✅ Translations updated and staged"
fi
fi
exit 0
```
Make it executable:
```bash
chmod +x .git/hooks/pre-commit
```
## Claude's Response to User
```
✅ CI/CD auto-translation setup complete!
I've created a GitHub Actions workflow that will automatically translate your i18n files.
**What I created:**
1. `.github/workflows/translate-i18n.yml` - GitHub Actions workflow
2. Instructions for setting up the API key secret
**How it works:**
1. When you push changes to `locales/en.json` (on main or develop branches)
2. GitHub Actions automatically:
- Installs Jta
- Translates to Chinese, Japanese, Korean, Spanish, French
- Uses incremental mode (only translates new/changed keys)
- Commits translations back to the repository
**Configuration:**
- Target languages: zh, ja, ko, es, fr
- Mode: Incremental (saves ~90% API cost on updates)
- Trigger: Changes to locales/en.json on main/develop
- API key: Uses OPENAI_API_KEY from GitHub secrets
**Next steps:**
1. Ensure `OPENAI_API_KEY` is set in your GitHub repository secrets
2. Commit and push the workflow file
3. Test by making a change to `locales/en.json`
**Optional enhancement:**
I can also create a pre-commit hook for local development, so translations
run automatically before you commit. Would you like that?
**Cost estimation:**
- First run (full translation): ~$1.50 for 100 keys × 5 languages
- Subsequent runs (incremental): ~$0.15-0.30 for typical updates
- The incremental mode will save significant costs over time
```
## Workflow Visualization
```mermaid
sequenceDiagram
participant Dev as Developer
participant Git as Git Repository
participant GHA as GitHub Actions
participant Jta as Jta
participant AI as AI Provider
Dev->>Git: Push changes to en.json
Git->>GHA: Trigger workflow
GHA->>GHA: Checkout repository
GHA->>GHA: Install Jta
GHA->>Jta: Run translation (incremental)
Jta->>AI: Translate changed keys
AI-->>Jta: Return translations
Jta->>Jta: Merge with existing translations
Jta-->>GHA: Translation complete
GHA->>Git: Commit translated files
Git-->>Dev: Translations available
```
## Testing the Workflow
### Test 1: Add New Keys
```bash
# Add new keys to en.json
vim locales/en.json
```
Add:
```json
{
"new": {
"feature": "New Feature",
"description": "This is a new feature"
}
}
```
Commit and push:
```bash
git add locales/en.json
git commit -m "feat: add new feature translations"
git push
```
**Expected result:**
- GitHub Actions triggers
- Translates 2 new keys to 5 languages (10 translations total)
- Commits translations back
- Total time: ~30 seconds
### Test 2: Modify Existing Keys
```bash
# Modify existing translation
vim locales/en.json
```
Change:
```json
{
"app": {
"welcome": "Welcome to our amazing platform!"
}
}
```
Commit and push:
```bash
git add locales/en.json
git commit -m "fix: improve welcome message"
git push
```
**Expected result:**
- GitHub Actions triggers
- Updates 1 modified key in 5 languages
- Preserves all other translations
- Total time: ~15 seconds
## Advanced Configuration
### Multi-Environment Setup
```yaml
name: Auto-translate i18n files
on:
push:
branches:
- main
- develop
paths:
- 'locales/en.json'
jobs:
translate:
runs-on: ubuntu-latest
strategy:
matrix:
environment: [staging, production]
steps:
# ... (installation steps)
- name: Translate
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
if [[ "${{ matrix.environment }}" == "production" ]]; then
# Use highest quality for production
jta locales/en.json --to zh,ja,ko,es,fr \
--provider anthropic \
--model claude-sonnet-4-5 \
--incremental -y
else
# Use faster/cheaper for staging
jta locales/en.json --to zh,ja,ko,es,fr \
--incremental -y
fi
```
### With Approval Step
```yaml
jobs:
translate:
runs-on: ubuntu-latest
environment:
name: translation-approval
# Requires manual approval before running
steps:
# ... (translation steps)
```
### With Slack Notifications
```yaml
- name: Notify Slack
if: steps.check_changes.outputs.changes == 'true'
uses: slackapi/slack-github-action@v1
with:
webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
payload: |
{
"text": "✅ Translations updated for commit ${{ github.sha }}",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Translations Updated*\nCommit: <${{ github.event.head_commit.url }}|${{ github.event.head_commit.message }}>"
}
}
]
}
```
## Best Practices
1. **Use incremental mode** in CI/CD to save costs
2. **Non-interactive mode** (`-y`) for automation
3. **Commit terminology** (`.jta/`) for consistency
4. **Set up branch protection** to require CI checks
5. **Monitor API usage** and costs
6. **Use caching** for jta binary to speed up workflow
## Cost Optimization
### Before (Manual Translation)
- Developer time: ~2 hours per update
- Inconsistent quality
- Often delayed or forgotten
### After (Automated with Jta)
- Developer time: 0 (fully automated)
- Consistent high quality (Agentic reflection)
- Instant updates
- API cost: ~$0.15-0.30 per update (incremental)
### Annual Savings Example
Assuming:
- 50 updates to en.json per year
- 5 target languages
- ~$0.20 per update (incremental)
**Cost:**
- API: $10/year
- Developer time saved: 100 hours/year
- ROI: Massive (100+ hours saved vs $10 API cost)
## Troubleshooting
### Workflow Fails: "API key not found"
**Solution:**
```bash
# Ensure secret is set correctly in GitHub
# Settings → Secrets → Actions → OPENAI_API_KEY
```
### Workflow Fails: "Permission denied"
**Solution:**
Add write permissions to workflow:
```yaml
permissions:
contents: write # Allow pushing commits
```
### Rate Limiting
**Solution:**
Add retry logic or reduce concurrency:
```yaml
- name: Translate with retry
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
for i in {1..3}; do
jta locales/en.json --to zh,ja,ko,es,fr \
--incremental \
--batch-size 10 \
--concurrency 1 \
-y && break
echo "Retry $i/3 after rate limit..."
sleep 60
done
```

303
skills/jta/examples/incremental-mode.md Normal file
View File

@@ -0,0 +1,303 @@
# Example: Incremental Translation
This example demonstrates how to update existing translations when you add new content to your source file.
## Scenario
User has already translated `en.json` to Chinese (`zh.json`). Now they've added 5 new keys and modified 2 existing keys in `en.json`. They want to update `zh.json` without re-translating everything.
## User Request
> "I added new keys to my en.json, please update the Chinese translation"
## Claude's Workflow
### Step 1: Understand the Context
Claude recognizes:
- **Task**: Update existing translation
- **Source file**: en.json
- **Target**: Chinese (zh.json already exists)
- **Mode**: Incremental (only translate changes)
### Step 2: Check Existing Translation
```bash
# Verify both files exist
ls -lh locales/en.json locales/zh.json
```
Output:
```
-rw-r--r-- 1 user staff 2.8K en.json (modified 5 minutes ago)
-rw-r--r-- 1 user staff 2.6K zh.json (created 2 days ago)
```
### Step 3: Execute Incremental Translation
```bash
# Use incremental mode
jta locales/en.json --to zh --incremental
```
### Step 4: Analyze Changes
Console output:
```
📄 Loading source file...
✓ Source file loaded (105 keys)
📄 Loading existing translation...
✓ Existing translation loaded (98 keys)
🔍 Analyzing changes...
Changes detected:
📝 New keys: 5
✏️ Modified keys: 2
✅ Unchanged keys: 93
🗑️ Deleted keys: 1
Breakdown:
New keys:
- settings.notification.email
- settings.notification.push
- user.preferences.theme
- user.preferences.language
- app.features.newFeature
Modified keys:
- app.welcome (content changed)
- user.credits (content changed)
Deleted keys:
- app.deprecated (will be removed from translation)
Continue with incremental translation? [Y/n]
```
### Step 5: User Confirms
Since the request included "update", Claude proceeds:
```bash
# Continue (non-interactive with -y would skip prompt)
# User presses Y or Claude proceeds automatically
```
### Step 6: Translate Only Changes
Console output:
```
📚 Loading terminology...
✓ Terminology loaded (8 terms from .jta/)
🤖 Translating 7 items (5 new + 2 modified)...
Processing ━━━━━━━━━━━━━━━━━━━━ 100% (7/7)
✓ Translation completed
🔄 Merging with existing translations...
✓ Merged 93 unchanged translations
✓ Added 5 new translations
✓ Updated 2 modified translations
✓ Removed 1 deleted key
💾 Saving translation...
✓ Saved to locales/zh.json
```
### Step 7: Show Statistics
```
📊 Incremental Translation Statistics
Target: Chinese (zh)
Total source keys: 105
New keys translated: 5
Modified keys: 2
Unchanged keys: 93 (preserved from previous translation)
Deleted keys: 1 (removed)
Translation performance:
Items translated: 7 (5 + 2)
Success: 7
Failed: 0
Duration: 8s
API calls: 2 (1 translate + 1 reflect)
Cost savings:
Without incremental: ~$0.30 (105 keys, 15 API calls)
With incremental: ~$0.03 (7 keys, 2 API calls)
Saved: ~90% ($0.27)
```
## Claude's Response to User
```
✅ Chinese translation updated successfully!
I've updated your zh.json with the changes from en.json using incremental mode.
**Changes applied:**
- ✨ Added 5 new translations
- ✏️ Updated 2 modified translations
- 🗑️ Removed 1 obsolete translation
- ✅ Preserved 93 unchanged translations
**New translations added:**
1. `settings.notification.email` → "电子邮件通知"
2. `settings.notification.push` → "推送通知"
3. `user.preferences.theme` → "主题偏好"
4. `user.preferences.language` → "语言偏好"
5. `app.features.newFeature` → "新功能"
**Updated translations:**
1. `app.welcome` → "欢迎来到 {appName}！开始您的旅程"
2. `user.credits` → "您的账户有 {count} 积分"
**Performance:**
- Duration: 8 seconds (vs ~45s for full re-translation)
- API calls: 2 (vs 15 for full re-translation)
- Cost: ~$0.03 (vs ~$0.30, saved 90%)
Your existing high-quality translations were preserved, and only the new/changed content was translated with Agentic reflection for quality assurance.
Would you like to update other languages as well?
```
## Comparison: Incremental vs Full Translation
### Full Translation (without --incremental)
```bash
jta en.json --to zh
```
- Translates all 105 keys
- Takes ~45 seconds
- 15 API calls
- Cost: ~$0.30
- May lose existing manual refinements
### Incremental Translation (with --incremental)
```bash
jta en.json --to zh --incremental
```
- Translates only 7 changed keys
- Takes ~8 seconds
- 2 API calls
- Cost: ~$0.03
- Preserves existing translations exactly
## How Incremental Detection Works
Jta uses content hashing to detect changes:
```
1. Load source (en.json)
2. Load existing translation (zh.json)
3. For each key in source:
- Calculate content hash of source value
- Compare with hash stored in previous translation
- If different → mark as "modified"
- If not in previous → mark as "new"
4. For each key in previous translation:
- If not in source → mark as "deleted"
5. Translate only "new" + "modified"
6. Merge with "unchanged"
7. Remove "deleted"
```
## Sample Changes
### Before (en.json - 2 days ago)
```json
{
"app": {
"welcome": "Welcome to {appName}!",
"deprecated": "Old feature (no longer used)"
},
"user": {
"credits": "You have {count} credits"
}
}
```
### After (en.json - now)
```json
{
"app": {
"welcome": "Welcome to {appName}! Start your journey",
"features": {
"newFeature": "New Feature"
}
},
"user": {
"credits": "Your account has {count} credits",
"preferences": {
"theme": "Theme",
"language": "Language"
}
},
"settings": {
"notification": {
"email": "Email notifications",
"push": "Push notifications"
}
}
}
```
### Changes Detected
- ✨ **New**: `app.features.newFeature`, `user.preferences.theme`, `user.preferences.language`, `settings.notification.email`, `settings.notification.push`
- ✏️ **Modified**: `app.welcome`, `user.credits`
- 🗑️ **Deleted**: `app.deprecated`
### Updated Translation (zh.json)
```json
{
"app": {
"welcome": "欢迎来到 {appName}！开始您的旅程",
"features": {
"newFeature": "新功能"
}
},
"user": {
"credits": "您的账户有 {count} 积分",
"preferences": {
"theme": "主题偏好",
"language": "语言偏好"
}
},
"settings": {
"notification": {
"email": "电子邮件通知",
"push": "推送通知"
}
}
}
```
## Best Practices
1. **Always use incremental mode for updates**
```bash
jta en.json --to zh --incremental
```
2. **Full re-translation when needed**
- After major terminology changes
- When quality is unsatisfactory
- When starting fresh
```bash
jta en.json --to zh # without --incremental
```
3. **CI/CD integration**
```bash
# In your CI pipeline
jta locales/en.json --to zh,ja,ko --incremental -y
```
4. **Multiple languages**
```bash
# Update all languages incrementally
jta en.json --to zh,ja,ko,es,fr --incremental -y
```