Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Documentation Translation (mdBook)

For translating CLI strings (the 403 keys in locales/app.yml consumed by the Rust binary), see translation instead. This page covers user-documentation translation only.

scuv’s user documentation lives in docs/src/*.md and is the single English source of truth. Translations are layered on top via gettext .po files under docs/po/, processed by the mdbook-i18n-helpers preprocessor at render time. Untranslated strings automatically fall back to English, so a partial translation is always deployable.

URL layout

  • English (canonical): https://ai-scream.ai/scoop-uv/
  • Korean: https://ai-scream.ai/scoop-uv/ko/

The locale switcher in the top-right of every page jumps between the same page on each side.

Prerequisites

# macOS
brew install gettext        # msginit / msgmerge / msgfmt
cargo install mdbook --version 0.5.3 --locked
cargo install mdbook-i18n-helpers --version 0.4.0 --locked

# Linux
sudo apt-get install -y gettext
# Then the same `cargo install` lines as above.

The cargo install step needs Rust 1.88 or newer (helpers’ upstream MSRV). The project’s rust-toolchain.toml pins 1.89, so the toolchain already in the repo is new enough — no +stable override needed.

Workflow: updating an existing translation

When you edit a page in docs/src/, the existing translations need to learn about the new / changed strings.

cd docs

# 1. Re-extract template (overwrites docs/po/messages.pot).
MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build -d po

# 2. Merge the new template into your locale's .po file.
#    --backup=none avoids leaving a stray ko.po~ around.
msgmerge --update --backup=none po/ko.po po/messages.pot

# 3. Open po/ko.po in your editor. Look for:
#    - new empty `msgstr ""` entries  →  add translations
#    - "#, fuzzy" markers              →  review and remove flag

docs/po/messages.pot is in .gitignore — it’s regenerated on every CI run, committing it would create churn. The locale .po files (docs/po/ko.po, etc.) ARE committed; they’re the translation memory.

Workflow: previewing a translated build

cd docs

# English (root)
mdbook build -d book
open book/index.html

# Korean (book/ko subdir)
MDBOOK_BOOK__LANGUAGE=ko mdbook build -d book/ko
open book/ko/index.html

mdbook serve works too if you want live reload:

MDBOOK_BOOK__LANGUAGE=ko mdbook serve -d book/ko

Workflow: adding a brand-new locale (e.g. ja)

cd docs

# Initialise an empty translation file.
msginit -i po/messages.pot -l ja -o po/ja.po --no-translator

# Translate msgids in po/ja.po (untranslated ones fall back to English).

# Add a CI build step for the new locale in
# .github/workflows/docs.yml, e.g.:
#
#   - name: Build Japanese (book/ja)
#     working-directory: docs
#     env:
#       MDBOOK_BOOK__LANGUAGE: ja
#     run: mdbook build -d book/ja
#
# Then expand the locale switcher in docs/theme/head.hbs to
# include the new locale link.

CI guard: stale translations

The Verify ko translations are in sync step regenerates the pot template from the current English source, runs msgmerge --update against the committed ko.po, and fails the build if the result differs. It runs in .github/workflows/docs-check.yml on PRs that touch the docs paths, and again in .github/workflows/docs.yml on v* tags. This means English edits land with their corresponding .po updates in the same PR, or they don’t land at all.

To fix a CI failure on this step:

cd docs
MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build -d po
msgmerge --update --backup=none po/ko.po po/messages.pot
git add po/ko.po
git commit --amend  # or as a separate fixup commit

Style guidelines

The same casual-tone guidelines from translation apply here. Don’t try to translate code samples or CLI commands literally — only the prose around them. Code-block content is shown verbatim regardless of locale; mdbook-i18n-helpers intentionally does not interpolate translations inside fenced code blocks for unmarked code, though it does extract code comments (# Install Python) as separate msgids so you can translate those if it helps readability.

Known limitations

  • Search index is built per-locale. Korean search results only hit Korean pages, English only hits English. This is the intended mdBook behaviour.
  • The locale switcher uses a JS-injected DOM element; users with JS disabled won’t see it. They can navigate via direct URL (/scoop-uv/ko/...) or browser bookmarks.
  • mdbook-i18n-helpers’ xgettext doesn’t extract HTML tables’ cell-by-cell content as separate msgids when the table is written in pipe-syntax — it extracts the whole table as a single block. For now this is acceptable; for fine-grained table translation we’d need to switch to per-row HTML tables in the source.