gh-hikanner-agent-skills-jta/skills/jta/examples/ci-cd-integration.md

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

# Create workflow directory if it doesn't exist
mkdir -p .github/workflows

Create workflow file:

# .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:

# 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:

# .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:

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

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

# Add new keys to en.json
vim locales/en.json

Add:

{
  "new": {
    "feature": "New Feature",
    "description": "This is a new feature"
  }
}

Commit and push:

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

# Modify existing translation
vim locales/en.json

Change:

{
  "app": {
    "welcome": "Welcome to our amazing platform!"
  }
}

Commit and push:

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

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

jobs:
  translate:
    runs-on: ubuntu-latest
    environment:
      name: translation-approval
      # Requires manual approval before running

    steps:
      # ... (translation steps)

With Slack Notifications

      - 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:

# Ensure secret is set correctly in GitHub
# Settings → Secrets → Actions → OPENAI_API_KEY

Workflow Fails: "Permission denied"

Solution: Add write permissions to workflow:

permissions:
  contents: write  # Allow pushing commits

Rate Limiting

Solution: Add retry logic or reduce concurrency:

      - 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