Translation

Actionbase documentation is translated using a Translation Memory (TM) workflow. English is the source language; translations are generated by applying exact-match TM lookups to the English MDX files.

Translation Memory (TM) is a key-value store that maps English source segments to their translations. Each document has its own TM file, managed at the document level.

How it works

en/*.mdx ──┐   ┌──────────────┐   ┌─────────────┐   ┌──────────┐
           ├──▶│ Parse MDX    │──▶│ TM Lookup   │──▶│ Generate │──▶ {lang}/*.mdx
tm/*.yaml ─┘   │ (segments)   │   │ HIT→target  │   │ output   │
               └──────────────┘   │ MISS→source │   └──────────┘
                                  └─────────────┘

The build command parses each English MDX into segments (title, description, headings, paragraphs, tables, list items). Each segment is looked up by exact string match — a HIT replaces the English text with the translation, and a MISS keeps the English text as-is. Non-translatable content (code blocks, imports, JSX, images) passes through unchanged.

Translated headings receive an explicit {#english-slug} anchor derived from the English source heading, ensuring cross-page links remain valid regardless of the translated heading text.

TM format

Each document has a YAML file at website/i18n/tm/{lang}/{doc-path}.yaml:

meta:
  contributors:
    - alice # GitHub username of human contributor
entries:
  - source: "Core Concepts"
    target: "Translated text"
    context: heading
  - source: "Actionbase is a database for serving user interactions."
    target: "Translated text for the paragraph"
    context: paragraph

Field	Description
meta.contributors	GitHub usernames of human contributors
entries[].source	English text (exact match key)
entries[].target	Translated text. Empty string ("") = untranslated
entries[].context	Segment type: frontmatter:title, frontmatter:description, heading, paragraph, table, list_item, summary, blockquote

File structure

website/i18n/
  tm/{lang}/{doc-path}.yaml            # Translation Memory per document
  scripts/translation-memory.ts        # TM tool
website/src/content/docs/
  *.mdx                                # English source (authoritative)
  {lang}/*.mdx                         # Generated from TM — do not edit
TRANSLATION.md                         # This file

CLI reference

All commands run from the website/ directory. The --lang flag defaults to ko and can be changed to target other languages.

npm run translate -- init              # Create empty TM files for new EN docs
npm run translate -- update            # Sync TM with updated EN source
npm run translate -- build             # Rebuild translated docs from TM
npm run translate -- validate          # Validate TM without writing files
npm run translate -- status            # Translation coverage (table)
npm run translate -- status --format=summary   # Coverage (markdown)
npm run translate -- --lang ko status  # Target a specific language (default: ko)

Command	Purpose
init	Create empty TM entries for documents that have no TM file yet
update	Add new segments (empty target), remove stale entries, preserve existing translations
build	Generate {lang}/*.mdx from TM lookups
validate	Dry-run build to catch YAML or segment errors
status	Show per-document HIT/MISS counts and coverage percentage

Flag	Description
--lang	Target language (default: ko)
--model	LLM model identifier. When set and a document has no human contributors, translated-by-{model}: true is added to the output frontmatter. Useful for external workflows that auto-generate TM via LLM

CI runs validate on pull requests and build on merge to main.

Known limitations

• Exact match only — any change to an English segment requires updating the corresponding TM entry. Use update to detect new/stale segments automatically.
• Multi-line JSX components (e.g., <LinkCard>) are passed through and may reformat slightly.