Skip to content

Internationalization (i18n) Guide

Memory Bank ships locale-aware .memory-bank/ template bundles. The skill defaults to English, but every user can install and initialize a bank in their preferred language.

Supported locales (v3.1.1):

Code Status Notes
en ✅ Full Source of truth
ru ✅ Full Complete Russian translation
es 🚧 Scaffold EN copy + TODO(i18n-es) banner — PRs welcome
zh 🚧 Scaffold EN copy + TODO(i18n-zh) banner — PRs welcome

What is localized

  • templates/locales/<lang>/.memory-bank/*.md — the 7 core files users see after mb init (status.md, roadmap.md, checklist.md, backlog.md, research.md, progress.md, lessons.md).

What stays English (contract)

These are machine-readable anchors — every mb-* script uses them across all locales. They must not be translated in any templates/locales/*/ file:

  • <!-- mb-active-plans --> / <!-- /mb-active-plans -->
  • <!-- mb-recent-done --> / <!-- /mb-recent-done -->
  • ## Ideas (in backlog.md)
  • ## ADR (in backlog.md)

Also English-only (by design):

  • commands/mb.md — prompt for the agent, not user-facing
  • scripts/*.sh CLI output / error messages
  • docs/ (except this file and the one-paragraph i18n note in README.md)
  • RULES.md — code-review rules, terminology is already English-heavy

User-facing CLI surface

# Install the skill with a preferred locale
memory-bank install --language ru

# Bootstrap .memory-bank/ in a project
memory-bank init --lang ru
# or via /mb in Claude Code:
#   /mb init --lang=ru

# Resolve / change the locale of an existing bank
scripts/mb-config.sh get lang
scripts/mb-config.sh set lang es

Resolution order (highest priority → lowest):

  1. --lang=<code> flag on the current command
  2. MB_LANG environment variable
  3. $MB_ROOT/.memory-bank/.mb-config → lang=<code>
  4. Heuristic auto-detect from existing bank content (Cyrillic → ru, else en) — result is written back to .mb-config to make subsequent runs deterministic.
  5. Default: en

Adding a new locale (contributor workflow)

Goal: turn a scaffold into a full translation, or add a brand-new language.

  1. Pick the locale code — use the ISO 639-1 two-letter code (fr, de, ja, …).
  2. Open a tracking issue on GitHub so duplicate work doesn't happen.
  3. Create the directory templates/locales/<lang>/.memory-bank/ if it does not yet exist, and seed every file from the en bundle.
  4. Translate the 7 core files. When done, remove the TODO(i18n-<lang>): banner line from the top of each file.
  5. Preserve canonical anchors (see "What stays English" above) — translate only prose, headings that are not anchors, and inline comments.
  6. Extend the CLI whitelist:
  7. scripts/mb-config.sh → SUPPORTED_LOCALES=(…)
  8. scripts/mb-init-bank.sh → SUPPORTED_LOCALES=(…)
  9. install.sh → VALID_LANGUAGES=(…)
  10. memory_bank_skill/cli.py → VALID_LANGUAGES = (…)
  11. Update tests in tests/pytest/test_locales_structure.py and tests/pytest/test_cli_lang.py — add the new code to SUPPORTED_LOCALES / FULL_LOCALES (after translation) or SCAFFOLD_LOCALES (while the bundle still contains TODO(i18n-<lang>) banners).
  12. Run the full suite:
PYTHONPATH="$PWD" python -m pytest tests/pytest/ --no-cov
bats tests/bats/test_mb_config.bats tests/bats/test_mb_init_bank.bats
bats tests/e2e/test_install_uninstall.bats
  1. Document the new locale in this file's table and in CHANGELOG.md.

Why this design

  • English as source of truth keeps the skill accessible to every contributor regardless of their native language.
  • Opt-in locales mean non-English speakers are first-class without forcing every user to read translated CLI strings.
  • Canonical English anchors keep the scripts locale-agnostic — we never have to maintain N parallel regex patterns.
  • Scaffold-first for new languages ships the infrastructure immediately and lets the community contribute translations asynchronously via PR.