Workshop Translator

🌐 Language: English | 한국어

AI-powered CLI tool for automatically translating AWS Workshop documents.

Key Features

• 🤖 AI-Powered Translation: High-quality translation using Claude models (Opus/Sonnet/Haiku)
• 📚 AWS Documentation Integration: Accurate terminology via MCP integration with official AWS docs
• ⚡ Parallel Processing: Process up to 5 files simultaneously with ThreadPoolExecutor
• 🔄 Session Resume: Continue interrupted work from where you left off
• 📊 Quality Management: 3-stage workflow: Translation → Review → Validation
• 👀 Local Preview: Instantly preview translation results

Architecture

Uses an Orchestrator-centric architecture.

┌─────────────────────────────────────────────────────────────────┐
│                      Orchestrator (main.py)                      │
│                    Claude Opus / Sonnet                          │
│                                                                  │
│  Core Principle: Only Orchestrator modifies tasks.md             │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   TaskManager     │
                    │   (Singleton)     │
                    │                   │
                    │ • Task state mgmt │
                    │ • Dependency check│
                    │ • tasks.md sync   │
                    └─────────┬─────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  Translator   │    │   Reviewer    │    │   Validator   │
│    Worker     │    │    Worker     │    │    Worker     │
│  (Stateless)  │    │  (Stateless)  │    │  (Stateless)  │
│ Returns only  │    │ Returns only  │    │ Returns only  │
│   results     │    │   results     │    │   results     │
└───────────────┘    └───────────────┘    └───────────────┘

Core Design Principles

Model Configuration

Workflow

Phase 1: Analysis/Design
    ├── analyze_workshop()     → Analyze workshop structure
    └── generate_design()      → Generate design document
           │
           ▼
Phase 2: Workflow Initialization
    └── initialize_workflow()  → Initialize TaskManager, create tasks.md
           │
           ▼
Phase 3: Translation
    └── run_translation_phase() → Execute parallel translation
           │
           ▼
Phase 4: Review
    └── run_review_phase()     → Review completed translations only
           │                   → Generate review_report.md
           ▼
Phase 5: Validation
    └── run_validate_phase()   → Validate translated+reviewed files only
           │                   → Generate validate_report.md
           ▼
Phase 6: Preview
    └── run_preview_phase()    → Run local preview server
           │                   → http://localhost:8080
           ▼
Phase 7: Complete
    └── get_workflow_status()  → Final status report

Orchestrator Tools

Generated Files

The following files are created in the translation/ directory during translation:

Installation

Install from PyPI (Recommended)

# Using uvx (run without installation)
uvx wstranslator

# Or install via pip
pip install wstranslator
wstranslator

Development Mode (Local Development)

# After cloning the repository
cd workshop-translator/WsTranslator

# Using uv
uv sync
uv run wstranslator

# Or using pip
pip install -e .
wstranslator

Usage

Interactive Mode

wstranslator

In interactive mode, the Orchestrator automatically progresses through the workflow.

Example conversation:

User: Please translate the /path/to/workshop directory to Korean

Orchestrator: Analyzing workshop structure...
              → Found 10 files
              → Workflow initialization complete
              → Starting translation (5 files in parallel)
              → Translation complete: 10/10 (100%)
              → Starting review...
              → Review complete. review_report.md generated
              → Validation complete. validate_report.md generated
              → Preview server started: http://localhost:8080

Session Resume

You can continue interrupted work from a previous session:

User: Please continue the previous translation work

Orchestrator: Resuming existing workflow. Loaded 25/30 tasks completed.
              → Starting translation of remaining 5 files...

Requirements

• Python 3.10+
• AWS credentials configured (AWS CLI or environment variables)
• Bedrock model access (Claude Opus, Sonnet, Haiku)

Environment Variables

# AWS region setting (default: us-west-2)
export AWS_REGION=us-west-2

# AWS profile setting
export AWS_PROFILE=your-profile

Dependencies

Key packages:

• strands-agents: AI agent framework
• strands-agents-tools: File read/write tools
• bedrock-agentcore: AWS Bedrock AgentCore runtime
• mcp: Model Context Protocol client
• boto3: AWS SDK

Troubleshooting

AWS Credentials Error

# AWS CLI configuration
aws configure

# Or set environment variables
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_REGION=us-west-2

Preview Server Error

# On macOS with execution permission issues
# Control-click preview_build file in Finder → Open

# File open limit error
ulimit -n 10240

MCP Connection Error

# Check uvx installation
uvx --version

# Test AWS Documentation MCP server
uvx awslabs.aws-documentation-mcp-server@latest

Developer Information

• Author: Jisan Bang (wltks2155@gmail.com)
• GitHub: https://github.com/onesuit/workshop-translator
• License: MIT
• Python Version: 3.10+