diff --git a/docs/superpowers/specs/2026-07-11-browser-extension-localization-design.md b/docs/superpowers/specs/2026-07-11-browser-extension-localization-design.md new file mode 100644 index 0000000..41352da --- /dev/null +++ b/docs/superpowers/specs/2026-07-11-browser-extension-localization-design.md @@ -0,0 +1,114 @@ +# Browser Extension Localization Design + +## Goal + +Add English and Russian localization to the Verstak browser extension with a +persisted manual `System / English / Russian` language selector. The extension +remains independent from the desktop application's language preference. + +## Scope + +The change covers: + +- all user-visible popup labels, hints, statuses, validation messages, and + receiver-state labels; +- the three browser context-menu titles; +- persisted language selection; +- Chromium and Firefox build packaging; +- automated tests for locale resolution, persistence, live popup updates, and + context-menu localization. + +Manifest name and description localization is not part of this milestone. The +existing English manifest values remain the fallback in both browser builds. + +## Locale Model + +The stored setting is named `language` and accepts only: + +- `system` (default); +- `en`; +- `ru`. + +`system` resolves the browser UI language through +`browser.i18n.getUILanguage()` / `chrome.i18n.getUILanguage()`. Popup code may +fall back to `navigator.language` when the extension i18n API is unavailable. +`ru` and `ru-*` resolve to Russian; every other value resolves to English. +Invalid or missing stored preferences normalize to `system`. + +## Catalogs and Runtime + +The extension owns framework-independent JSON catalogs: + +```text +shared/locales/en.json +shared/locales/ru.json +``` + +A small shared runtime provides: + +- preference normalization; +- system-locale resolution; +- key lookup with English and literal fallback; +- `{parameter}` interpolation. + +The runtime has no dependency on desktop, the plugin SDK, DOM APIs, or external +packages. It is loaded by both popup and background scripts. + +Both catalogs must contain identical string-only keys. The build copies them +into `dist/chromium/locales` and `dist/firefox/locales` together with the shared +runtime. + +## Popup Behavior + +The existing settings section gains a labeled language `