feat: add automatic documentation translation workflow

[guzus]

Summary

• Add GitHub workflow for automatic documentation translation to 5 languages (ko, zh, ja, es, pt)
• Add workflow to protect translated docs from direct edits
• Add language selector to website docs page
• Update pages workflow to handle all HTML files

Features

Translation Workflow (translate-docs.yml)

• Triggers on changes to English documentation (wiki/*.md, website/docs.html)
• Uses Claude Code to translate documentation in parallel for each language
• Creates PR with translated content automatically
• Supports manual trigger with force translate option

Protection Workflow (protect-translated-docs.yml)

• Blocks PRs that directly modify translated documentation
• Only English sources should be manually edited
• Allows automated translation PRs from the bot

Website Language Selector

• Dropdown in navigation to switch between languages
• Stores preference in localStorage
• Redirects to language-specific docs (docs-ko.html, docs-zh.html, etc.)

Supported Languages

• Korean (ko) - Strong crypto/prediction market community
• Chinese (zh) - Largest developer population
• Japanese (ja) - Strong tech community
• Spanish (es) - Large global developer population
• Portuguese (pt) - Large Brazilian developer community

Test plan

• Verify translate-docs.yml workflow syntax is valid
• Verify protect-translated-docs.yml workflow triggers on correct paths
• Verify language selector UI works in docs.html
• Test manual workflow dispatch with force_translate option
• Verify pages workflow processes all HTML files

Generated with Claude Code

[claude]

PR Review: Automatic Documentation Translation Workflow

I've reviewed PR #74 and have the following feedback organized by category:

✅ Strengths

1. Well-structured approach: The separation into three workflows (translate, protect, pages) is clean and logical
2. Good documentation: The workflow comments clearly explain the purpose and supported languages
3. Protection mechanism: The protect-translated-docs.yml workflow is a good safeguard against manual edits to auto-generated translations
4. Language selector UI: The implementation is clean and uses localStorage for persistence

---

🔴 Critical Issues

1. Workflow will fail - Missing checkout before git operations

Location: .github/workflows/translate-docs.yml:203-213

Problem: The create-pr job attempts to run git commands but never checks out the repository. This will fail because there's no git repository to operate on.

Fix: Add checkout step before the git operations

2. Workflow coordination issue - Changes won't be visible

Location: .github/workflows/translate-docs.yml:95-98 (translate job) and lines 203-213 (create-pr job)

Problem: The translate job runs using the Claude Code action which modifies files, but these changes are made in isolated job runners. The create-pr job starts with a fresh checkout and won't see any of the translation changes from the previous job. The jobs don't share a workspace or use artifacts to transfer files.

Fix: Either:

• Combine the translation and PR creation into a single job
• Use artifacts to transfer modified files between jobs
• Use a matrix strategy where each language creates its own PR

3. Security: Overly permissive permissions

Location: .github/workflows/translate-docs.yml:90-93

Problem: The translate job (which runs in a matrix across 5 languages) has contents: write and id-token: write permissions, but it only needs to read files for translation. The PR creation happens in a separate job.

Fix: Reduce permissions in the translate job to contents: read

4. No validation of translation output

Problem: The workflow assumes Claude Code successfully translated files but never verifies:

• Were the target files actually created?
• Are they valid markdown/HTML?
• Did the file structure get preserved?
• Are code blocks and links still intact?

Recommendation: Add validation steps after translation

---

⚠️ Design & Architecture Issues

5. Inefficient workflow design

Current flow:

1. Detect changes
2. Run 5 translation jobs in parallel (matrix strategy) ✅
3. Wait for ALL translations to complete
4. Create a SINGLE PR with all changes

Problem: If one language translation fails or times out (30min limit), the entire workflow fails and NO translations are committed, even the successful ones.

Better approach: Use artifacts to transfer translated files, so partial successes can still be committed.

6. Prompt engineering issues

Location: .github/workflows/translate-docs.yml:122-176

Problems:

• The prompt is constructed with sed substitution which is error-prone
• File paths are passed as comma-separated strings that may not be properly parsed
• The prompt doesn't specify how to handle missing directories
• No validation that translation actually occurred

7. Hardcoded language list (DRY violation)

The supported languages ko,zh,ja,es,pt are hardcoded in multiple places:

• Line 45 (env variable)
• Line 40 (workflow_dispatch default)
• Line 97 (matrix)
• Line 15-20 (paths in protect workflow)
• Line 631-645 (website HTML)

Problem: Adding/removing a language requires changes in 5+ places.

---

🟡 Code Quality Issues

8. Language selector JavaScript could use improvement

Location: website/docs.html:1338-1412

Issues:

• Inline JavaScript in a large HTML file (hard to maintain/test)
• No error handling for localStorage access (can fail in private browsing)
• The redirect logic could be simplified

Suggested improvement: Add try-catch for localStorage operations

9. Missing error scenarios

What happens if:

• Claude Code API is down or rate-limited?
• Translation times out (30min limit)?
• PR creation fails due to conflicts?
• A translated file is corrupted?

Recommendation: Add continue-on-error: true and failure notifications

---

🔒 Security Considerations

10. Token usage documentation

The workflow uses CLAUDE_CODE_OAUTH_TOKEN which is good (stored as secret).

Recommendation: Document in the PR or README:

• How to obtain this token
• What permissions it needs
• How to rotate it if compromised
• Cost implications (each translation consumes API credits)

11. Allowed tools restriction ✅

Location: .github/workflows/translate-docs.yml:185-189

Restricting tools to Read, Write, Glob, Grep is a security best practice. Well done!

---

📝 Documentation & Maintainability

12. Missing documentation

What's missing:

• How to add a new language
• How to trigger a re-translation of all docs
• What to do if a translation is incorrect
• Cost/time estimates for translations
• Troubleshooting guide

Recommendation: Add documentation about the translation system (e.g., wiki/TRANSLATION.md)

13. Code follows CLAUDE.md conventions ✅

Based on the project's CLAUDE.md:

• ✅ Focused and clean structure
• ✅ No unnecessary files created
• ⚠️ Proactive debugging needed (workflows should be tested per guideline Create debugging frontend for trading strategies #5)

---

📋 Testing & Validation Concerns

14. No test plan execution

The PR description includes a test plan, but these are all unchecked.

Recommendation: Before merging:

1. Use actionlint or GitHub's workflow validator to check syntax
2. Create a test PR modifying a translated file to verify protection workflow triggers
3. Test the language selector in a browser (including private browsing mode)
4. Trigger the workflow manually with force_translate: true
5. Deploy to a test environment and verify all HTML files render correctly

---

🎯 Recommendations Summary

Must fix before merging (Critical):

1. ✅ Add checkout step to create-pr job
2. ✅ Fix job coordination (use artifacts or combine jobs)
3. ✅ Reduce permissions in translate job
4. ✅ Add validation that translations were created

Should fix (Important):
5. Improve error handling with continue-on-error
6. Improve prompt engineering (better file list handling)
7. Add validation steps for translation output
8. Create documentation for the translation system
9. Document the token requirements and setup process

Nice to have (Quality of life):
10. Refactor language selector JavaScript
11. Add localStorage error handling
12. Add cost/performance estimates
13. Consider using language list as single source of truth

---

💡 Alternative Approach to Consider

Option: Artifact-based approach (recommended)

• Each translate job uploads an artifact
• create-pr job downloads all artifacts and creates one PR
• If some translations fail, others still get committed
• Better fault tolerance and debugging

---

Conclusion

This is a well-intentioned PR that adds valuable i18n capabilities. The overall architecture is sound, but there are critical workflow issues that will prevent it from working as-is. The main problems are:

1. Broken job coordination - changes made in one job won't be visible to the next
2. Missing checkout - git operations will fail
3. No validation - workflow assumes success without checking

Once these are fixed, this will be a solid addition to the project.

Recommendation: Request changes to fix critical issues #1-4, then re-review.