Skip to content

Add TM-based translation workflow with contributor guide#203

Merged
em3s merged 24 commits intomainfrom
feat/tm-based-i18n
Mar 3, 2026
Merged

Add TM-based translation workflow with contributor guide#203
em3s merged 24 commits intomainfrom
feat/tm-based-i18n

Conversation

@eazyhozy
Copy link
Copy Markdown
Member

@eazyhozy eazyhozy commented Feb 24, 2026

Summary

Add TM-based translation workflow for Korean docs, with contributor-friendly
documentation and CI integration.

Closes #202

Changes

  • Add website/i18n/scripts/translation-memory.py — CLI tool with init, update, build, validate, status subcommands
  • Add status --format=summary option for markdown output in CI Job Summary
  • Move TM and glossary under website/i18n/ (tm/, glossary/)
  • Remove legacy translation-prompt.md
  • Include 2 example TM files (faq.yaml, introduction.yaml) as representative samples; remaining TM files will be added in a follow-up PR
  • Restructure TRANSLATION.md — contributor guide at the top (step-by-step example, local preview, glossary reference), technical architecture at the bottom
  • Enhance CONTRIBUTING.md translations section with actionable quick-start steps
  • Add CI workflow (translation.yml):
    • push/workflow_dispatch → build + auto-PR
    • pull_request → validate + status report
    • workflow_dispatch accepts build input (default: true) for validate-only runs
    • Job Summary renders markdown table instead of code block

Note: Generated ko/*.mdx files are not included — they will be created automatically by the CI workflow after this PR merges.

How to Test

# Validate TM entries
python website/i18n/scripts/translation-memory.py --lang ko validate

# Check status (table format)
python website/i18n/scripts/translation-memory.py --lang ko status

# Check status (CI summary format)
python website/i18n/scripts/translation-memory.py --lang ko status --format=summary

# Build translated docs and preview locally
python website/i18n/scripts/translation-memory.py --lang ko build
cd website && npm run dev
# Open http://localhost:4321/ko/

🤖 Generated with Claude Code

Introduce a Translation Memory workflow for translating Actionbase
documentation. English is the source language; translations are
generated by applying exact-match TM lookups to MDX files.

- Add translation-memory.py with init/update/build/status commands
- Add 36 Korean TM files with quality-reviewed translations
- Add glossary (terms + preserve list) at glossary/ko.yaml
- Add TRANSLATION.md documenting the full workflow
- Update CONTRIBUTING.md to reference TRANSLATION.md
- Add __pycache__/ to .gitignore

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@eazyhozy eazyhozy self-assigned this Feb 24, 2026
@eazyhozy eazyhozy changed the title feat(i18n): add TM-based translation workflow for Korean docs ㅁdd TM-based translation workflow for Korean docs Feb 24, 2026
@eazyhozy eazyhozy changed the title ㅁdd TM-based translation workflow for Korean docs Add TM-based translation workflow for Korean docs Feb 24, 2026
eazyhozy and others added 11 commits February 24, 2026 17:40
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… subcommand

- Move tm/ → website/i18n/tm/, glossary/ → website/i18n/glossary/
- Remove legacy website/i18n/glossary.json and translation-prompt.md
- Add validate subcommand (build without file writes, exit 1 on errors)
- Add status --docs filter for CI affected-docs reporting
- Add CI workflow with matrix-based multi-lang support and trigger mode detection
- Update TRANSLATION.md paths and validate documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use I18N_DIR as base path instead of OSS_ROOT for cleaner path resolution.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ontext)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add --format option to the status subcommand with two choices:
- table (default): original plain-text table output
- summary: markdown format for CI Job Summary

Also fix hit counting to only count entries with non-empty targets,
giving a more accurate picture of actual translation progress.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Restructure TRANSLATION.md to put contributor guide at the top:
- Add step-by-step example with TM init for new documents
- Add local preview instructions (validate, build, dev server)
- Add glossary reference and CI result explanation
- Use {lang} placeholders for language-neutral examples
- Move technical architecture sections to the bottom

Enhance CONTRIBUTING.md translations section with actionable
quick-start steps and status command tip.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…workflow

Add workflow_dispatch 'build' input (default: true) so the workflow
can be manually triggered in validate-only mode (build: false).

Improve job summary output:
- Use --format=summary for markdown table rendering
- Handle manual dispatch gracefully (show all docs when no PR context)
- workflow_dispatch input takes priority over event-based detection

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Keep only faq.yaml and introduction.yaml as representative examples.
Remaining TM files will be added in a follow-up PR after the
translation workflow lands on main.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@eazyhozy eazyhozy changed the title Add TM-based translation workflow for Korean docs feat(i18n): add TM-based translation workflow with contributor guide Feb 25, 2026
@eazyhozy eazyhozy changed the title feat(i18n): add TM-based translation workflow with contributor guide Add TM-based translation workflow with contributor guide Feb 25, 2026
@eazyhozy eazyhozy marked this pull request as ready for review February 25, 2026 01:19
@eazyhozy eazyhozy requested a review from em3s as a code owner February 25, 2026 01:19
@dosubot dosubot bot added size:XXL This PR changes 1000+ lines, ignoring generated files. enhancement New feature or request labels Feb 25, 2026
@eazyhozy
Copy link
Copy Markdown
Member Author

@em3s Requesting your review.

A few areas I'd especially appreciate feedback on:

  • translation-memory.py — the MDX parser and TM lookup logic
  • translation.yml — CI workflow design (push → auto-PR, PR → validate + status)
  • TRANSLATION.md — whether the contributor guide reads well top-to-bottom

Only 2 example TM files are included (faq.yaml, introduction.yaml). The rest of the TM data and generated ko/*.mdx files will come in follow-up PRs once this merges.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
CONTRIBUTING.md Outdated
## Translations

We welcome documentation translations. When submitting translation PRs, please submit **one section (folder) per PR** rather than translating all pages at once. This makes reviews manageable and allows incremental progress.
We welcome documentation translations! The easiest way to start:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about just:

We welcome documentation translations.

eazyhozy and others added 6 commits February 25, 2026 11:25
Replace the Python TM CLI with a TypeScript equivalent run via tsx.
Add js-yaml, @types/js-yaml, tsx dependencies and an npm "translate"
script. Delete the original Python file.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove casual tone, add TM concept explanation, update all Python
commands to npm run translate, and reduce TRANSLATION.md to
approximately 70% of original volume.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add 6 missing entries to introduction.yaml (1 paragraph + 5 table rows)
- Fix empty targets in faq.yaml (FAQ title, Java 17)
- Rebuild ko/faq.mdx and ko/introduction.mdx from updated TM

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Generate {#english-slug} anchors on Korean headings during TM build
to preserve cross-page link compatibility. Also remove invalid
roadmap/#exploring hash from introduction TM entry.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
eazyhozy and others added 2 commits February 25, 2026 14:58
No Python scripts remain after TypeScript port.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move contributor workflow to CONTRIBUTING.md, keep technical
process documentation in TRANSLATION.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@eazyhozy
Copy link
Copy Markdown
Member Author

@em3s

Addressed offline review feedback:

  1. Port translate script to TypeScript — Runs via npm run translate, no Python dependency. CI updated.
  2. Streamline translation docs — Unified tone, separated contributor guide (CONTRIBUTING.md) from technical reference (TRANSLATION.md).
  3. Include example build outputko/faq.mdx and ko/introduction.mdx committed with 100% TM coverage.

eazyhozy and others added 2 commits February 26, 2026 17:00
- Remove glossary from OSS build (used only by external TM pipeline)
- Move LLM model info from TM meta to --model CLI flag
- Add translated-by frontmatter only when --model is set and no human
  contributors exist
- Improve CONTRIBUTING.md with step-by-step translation guide and TM
  example
- Remove kanana-2 from TM contributors (humans only)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove glossary path triggers and detection from translation workflow
- Add --lang flag to CONTRIBUTING.md CLI examples (default: ko)
- Document --lang and --model flags in TRANSLATION.md
- Describe --model use case for external LLM-based TM generation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@eazyhozy
Copy link
Copy Markdown
Member Author

@em3s Addressed review feedback:

  • Remove glossary from this PR (only used by external TM pipeline)
  • TM meta.contributors is humans only; LLM model info via --model CLI flag
  • Rewrite CONTRIBUTING.md Translations section with step-by-step guide and TM example
  • Fix TRANSLATION.md diagram, add --lang/--model flag docs
  • Clean up stale glossary refs in CI workflow

@em3s
Copy link
Copy Markdown
Contributor

em3s commented Mar 3, 2026

LGTM 👍

@em3s em3s merged commit d755312 into main Mar 3, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: Translation Memory (TM) based i18n workflow

2 participants