Skip to content

Internationalization (i18n) Guide

Memory Bank has two language settings: the language the agent answers in (and writes code comments in), and the language of the .memory-bank/ templates. The skill defaults to English.

Supported locales:

Code Status Notes
en ✅ Full Source of truth
ru ✅ Full Russian
es ✅ Full Spanish
pt ✅ Full Portuguese
zh ✅ Full Chinese (Simplified)

Response and code-comment language

# Global default for every project (all clients: Claude Code, Codex, pi, OpenCode, …)
memory-bank install --language ru                         # answers and code comments in Russian
memory-bank install --language ru --comments-language en  # answers in Russian, comments in English

Both settings persist in the install manifest, so mb-upgrade.sh reapplies them. The rule strings live in memory_bank_skill/_texttools.py (LANGUAGE_NAMES); every client's rules file is rendered from that one source.

One project can override the global choice (/mb language):

python3 <skill>/scripts/mb-language.py set ru --comments en   # this project only
python3 <skill>/scripts/mb-language.py off                    # back to the global choice

It writes a managed block (<!-- mb-language:start -->) at the top of the project's AGENTS.md and CLAUDE.md, creating them if missing. Codex, OpenCode, Pi, and Cursor read AGENTS.md, Claude Code reads CLAUDE.md; each loads project instructions after its global ones, and the block says it overrides the global rule. At the top of the file it stays inside Codex's 32 KiB project-doc limit. Codex reads project AGENTS.md only in a trusted project.

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)
  • # Architecture Decision Records (header of adr.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: add a 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 (prose only; see the anchors below).
  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. scripts/mb-upgrade.sh → UPGRADE_VALID_LANGUAGES=(…)
  11. memory_bank_skill/cli.py → VALID_LANGUAGES = (…)
  12. memory_bank_skill/_texttools.py → LANGUAGE_NAMES (display name for the rule text)
  13. Update tests in tests/pytest/test_locales_structure.py and tests/pytest/test_cli_lang.py — add the new code to SUPPORTED_LOCALES.
  14. 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.