Internationalization (i18n)

Mark It Down ships with translations for English (default) plus Spanish, French, German, and Arabic (RTL). VSCode picks the locale from its own UI language setting; you don't need to configure the extension separately.

What's localised

• Manifest strings — command titles, view names, settings descriptions, the activity-bar container, the "no notes yet" welcome message. Source of truth: package.nls.json (English fallback) + per-locale package.nls.<lang>.json.
• Runtime strings — status-bar labels, empty-state hints, exporter notifications. Source of truth: l10n/bundle.l10n.json + per-locale l10n/bundle.l10n.<lang>.json.

Locales shipped

For RTL: VSCode's locale loader sets dir="rtl" on the workbench automatically when the active language is Arabic. Sidebar, modals, and status bar mirror without code changes. The custom markdown editor webview inherits the workbench direction so headings, lists, and tables render right-to-left.

How VSCode resolves locales

1. The user picks a language via Configure Display Language (it downloads the matching VSCode language pack).
2. On extension load, VSCode looks for package.nls.<lang>.json alongside package.json and substitutes %key% references in the manifest.
3. Runtime strings resolve via vscode.l10n.t(key, …) by reading l10n/bundle.l10n.<lang>.json. The l10n field in package.json points the resolver at this directory.
4. Missing keys fall back to the English source — there's no [Untranslated] marker shown to the user.

Calling t() in code

The wrapper around vscode.l10n.t keeps call sites stable across runtime changes and makes the bundle key easy to grep.

Positional placeholders use {0}, {1} … in the bundle string and the extra args fill them in order. Don't concatenate translated strings — build a single bundle key per sentence so locales can re-order it.

Parity check

scripts/check-i18n.mjs enforces that every package.nls.<lang>.json and l10n/bundle.l10n.<lang>.json has exactly the same keys as the English source — no missing keys, no extras. CI runs it on every PR via .github/workflows/ci.yml.

Run locally:

$ pnpm check-i18n

A clean output reads i18n parity OK — checked 8 locale file(s).

Adding a new locale

1. Copy package.nls.json to package.nls.<lang>.json and translate each value.
2. Copy l10n/bundle.l10n.json to l10n/bundle.l10n.<lang>.json and translate each value.
3. Run npm run check-i18n — fix any reported discrepancies.
4. Run npm test — the parity vitest in tests/unit/i18n/parity.test.ts asserts the same invariant.
5. Update this doc's "Locales shipped" table.

VSCode auto-discovers the new locale on the next launch — no manifest declaration needed.

Adding a new key

1. Add it to package.nls.json (or l10n/bundle.l10n.json) first.
2. Add the matching key to every <lang> file in that family.
3. Reference it in the manifest as %key% or in code via t('key').
4. The parity check + vitest will catch any locale you forgot.

Testing

$ pnpm dlx vitest run tests/unit/i18n

11 tests cover: at-least-4 locales beyond English (per family), per-file exact-key parity for each locale, every value is a non-empty string.

Limitations

• Webview content (the custom markdown editor's toolbar buttons, table-export labels, mermaid controls) is currently English-only. Plumbing the bundle into the webview means either (a) shipping the bundle as JSON and resolving on the renderer side, or (b) sending the resolved strings via the existing update postMessage. Either is a natural follow-up.
• Slideshow preview (reveal.js client) and the published static site also remain English-only — they don't run in a VSCode locale context.
• Translations beyond English were drafted in a single pass and not reviewed by native speakers; PRs to refine es/fr/de/ar idiom are very welcome.