Compare commits

...

3 Commits

7 changed files with 608 additions and 1 deletions

View File

@ -0,0 +1,328 @@
# Browser Extension Localization Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Add persisted `System / English / Russian` language selection to the browser extension, localizing popup chrome and context menus in Chromium and Firefox.
**Architecture:** A framework-independent `shared/i18n.js` resolves preferences and loads extension-owned JSON catalogs. Popup and background both consume it; background owns persistence and context-menu recreation, while popup performs immediate DOM translation and sends settings updates.
**Tech Stack:** WebExtension APIs, plain ES5-compatible JavaScript, JSON catalogs, Node `assert`/`vm` tests, existing Node build script.
## Global Constraints
- Store only `system`, `en`, or `ru`; missing/invalid values normalize to `system`.
- `ru` and `ru-*` browser UI locales resolve to Russian; all other system locales resolve to English.
- Keep the extension language independent from desktop settings.
- Add no runtime dependency and no manifest-localization scope.
- Never translate receiver URLs, tokens, file names, user content, or raw receiver error text.
- Preserve receiver URL/token values when language changes.
- Both browser distributions must contain `i18n.js`, `locales/en.json`, and `locales/ru.json`.
---
### Task 1: Shared Locale Runtime and Catalog Contract
**Files:**
- Create: `shared/i18n.js`
- Create: `shared/locales/en.json`
- Create: `shared/locales/ru.json`
- Create: `scripts/test-i18n.js`
- Modify: `package.json`
**Interfaces:**
- Produces: `globalThis.VerstakBrowserI18n.normalizePreference(value)`.
- Produces: `globalThis.VerstakBrowserI18n.resolveLocale(preference, systemLocale)`.
- Produces: `globalThis.VerstakBrowserI18n.loadCatalogs(loadJSON)` returning `Promise<{en,ru}>`.
- Produces: `globalThis.VerstakBrowserI18n.createTranslator(catalogs, locale)` returning `t(key, params, fallback)`.
- [ ] **Step 1: Write the failing runtime/catalog test**
Create `scripts/test-i18n.js` that loads `shared/i18n.js` in `vm`, reads both JSON catalogs, and asserts:
```js
assert.strictEqual(i18n.normalizePreference('de'), 'system');
assert.strictEqual(i18n.resolveLocale('system', 'ru-RU'), 'ru');
assert.strictEqual(i18n.resolveLocale('system', 'uk-UA'), 'en');
assert.strictEqual(i18n.resolveLocale('en', 'ru-RU'), 'en');
assert.deepStrictEqual(Object.keys(ru).sort(), Object.keys(en).sort());
assert.ok(Object.values(en).every((value) => typeof value === 'string'));
assert.ok(Object.values(ru).every((value) => typeof value === 'string'));
assert.strictEqual(i18n.createTranslator({ en, ru }, 'ru')('status.queued'), 'В очереди до запуска Верстака');
assert.strictEqual(i18n.createTranslator({ en, ru }, 'en')('error.value', { error: 'offline' }), 'Error: offline');
```
- [ ] **Step 2: Run the test and confirm RED**
Run: `node scripts/test-i18n.js`
Expected: FAIL because `shared/i18n.js` and catalogs do not exist.
- [ ] **Step 3: Implement the minimal shared runtime**
Implement an IIFE exporting the four functions. `loadCatalogs(loadJSON)` must call `loadJSON('en')` and `loadJSON('ru')`; translation lookup order is selected catalog, English catalog, explicit fallback, key. Interpolation replaces `{name}` only when `params` owns that property.
Catalogs must define identical keys for:
```text
popup.subtitle
label.receiver
label.pending
label.url
label.file
label.receiverUrl
label.pairingToken
label.language
action.sendPage
action.sendFile
action.retryPending
action.save
hint.contextMenu
receiver.online
receiver.offline
receiver.unknown
language.system
language.en
language.ru
status.sending
status.queued
status.done
status.readingFile
status.saved
error.chooseFile
error.fileTooLarge
error.invalidReceiverUrl
error.value
context.sendPage
context.sendSelection
context.sendLink
```
- [ ] **Step 4: Add the test to `npm test` and verify GREEN**
Set:
```json
"test": "node scripts/test-protocol.js && node scripts/test-i18n.js && node scripts/test-popup-settings.js"
```
Run: `node scripts/test-i18n.js`
Expected: `browser extension localization runtime tests passed`.
- [ ] **Step 5: Commit the shared contract**
```bash
git add shared/i18n.js shared/locales scripts/test-i18n.js package.json
git commit -m "feat: add browser extension localization runtime"
```
---
### Task 2: Persisted Language and Localized Context Menus
**Files:**
- Modify: `shared/background.js`
- Modify: `chromium/manifest.json`
- Modify: `firefox/manifest.json`
- Create: `scripts/test-background-i18n.js`
**Interfaces:**
- Consumes: `VerstakBrowserI18n.loadCatalogs`, `normalizePreference`, `resolveLocale`, `createTranslator`.
- Produces: persisted `settings.language` and context-menu recreation after `saveSettings`.
- [ ] **Step 1: Write the failing background test**
Load `protocol.js`, `queue.js`, `i18n.js`, and `background.js` into `vm` with fake storage/context-menu APIs. Seed `settings.language = 'ru'`, trigger `runtime.onInstalled`, and assert:
```js
assert.deepStrictEqual(menuTitles, [
'Отправить страницу в Верстак',
'Отправить выделение в Верстак',
'Отправить ссылку в Верстак',
]);
```
Send a `saveSettings` message with `{ receiverUrl, receiverToken, language: 'en' }`, then assert stored receiver fields are unchanged and menu titles become English.
- [ ] **Step 2: Run the test and confirm RED**
Run: `node scripts/test-background-i18n.js`
Expected: FAIL because background defaults contain no language and menu titles are literal English.
- [ ] **Step 3: Implement background localization**
Add `language: 'system'` to `DEFAULT_SETTINGS`. Normalize it in `getSettings`/`saveSettings`. Load catalogs with:
```js
function loadLocaleCatalogs() {
return localeCatalogs || i18n.loadCatalogs(function (locale) {
return fetch(ext.runtime.getURL('locales/' + locale + '.json')).then(function (response) {
if (!response.ok) throw new Error('catalog load failed: ' + locale);
return response.json();
});
});
}
```
Make `setupContextMenus()` resolve settings plus catalogs, choose
`ext.i18n.getUILanguage()` with English fallback, and create the three menu
titles via `t('context.sendPage')`, `t('context.sendSelection')`, and
`t('context.sendLink')`. Call it after language settings are saved.
- [ ] **Step 4: Load `i18n.js` before background code in both manifests**
- Chromium service worker remains bundled by the build concatenation order.
- Firefox `background.scripts` becomes `protocol.js`, `api.js`, `queue.js`, `i18n.js`, `background.js`.
Also append `node scripts/test-background-i18n.js` to the `test` script in
`package.json` now that the test file exists.
- [ ] **Step 5: Verify and commit**
Run: `node scripts/test-background-i18n.js`
Expected: `browser extension background localization tests passed`.
```bash
git add shared/background.js chromium/manifest.json firefox/manifest.json scripts/test-background-i18n.js
git commit -m "feat: localize browser extension context menus"
```
---
### Task 3: Popup Language Selector and Live Translation
**Files:**
- Modify: `shared/popup/popup.html`
- Modify: `shared/popup/popup.js`
- Modify: `shared/popup/popup.css`
- Modify: `scripts/test-popup-settings.js`
**Interfaces:**
- Consumes: state `settings.language` from background and the shared translator.
- Produces: immediate popup translation plus a `saveSettings` message containing receiver URL, token, and language.
- [ ] **Step 1: Extend the popup test and confirm RED**
Add fake elements for every localized ID plus `language-select`, mock catalog fetches, `browser.i18n.getUILanguage()`, and `document.documentElement.lang`. Assert initial `system` with `ru-RU` renders Russian. Change select value to `en`, dispatch `change`, flush promises, then assert:
```js
assert.strictEqual(elements['capture-page'].textContent, 'Send Page');
assert.strictEqual(elements['receiver-state'].textContent, 'Unknown');
assert.strictEqual(document.documentElement.lang, 'en');
assert.strictEqual(savedSettings.language, 'en');
assert.strictEqual(savedSettings.receiverUrl, initialState.settings.receiverUrl);
assert.strictEqual(savedSettings.receiverToken, initialState.settings.receiverToken);
```
- [ ] **Step 2: Add popup markup**
Load `../i18n.js` before `popup.js`, give all static user-visible elements stable IDs, and add:
```html
<label id="language-label" for="language-select">Language</label>
<select id="language-select">
<option value="system">System</option>
<option value="en">English</option>
<option value="ru">Русский</option>
</select>
```
- [ ] **Step 3: Implement asynchronous popup initialization and live switch**
Load both catalogs through `ext.runtime.getURL`, resolve the locale from saved
preference plus browser UI language, and apply all static text through one
`applyLocale(preference)` function. `render(state)` localizes
online/offline/unknown. Known statuses and validations use catalog keys; raw
error messages are wrapped only when needed by `error.value`.
The select `change` handler must call `applyLocale` before awaiting background
storage, then send all three settings fields. The existing Save button also
sends the selected language.
- [ ] **Step 4: Style the select consistently and verify GREEN**
Share the existing input box model/colors with `select` and keep the popup
minimum width unchanged.
Run: `node scripts/test-popup-settings.js`
Expected: `browser extension popup localization/settings tests passed`.
- [ ] **Step 5: Commit**
```bash
git add shared/popup scripts/test-popup-settings.js
git commit -m "feat: add browser extension language selector"
```
---
### Task 4: Distribution Packaging, Documentation, and Full Verification
**Files:**
- Modify: `scripts/build-extension.js`
- Modify: `README.md`
- Test: `scripts/test-i18n.js`
- Test: `scripts/test-background-i18n.js`
- Test: `scripts/test-popup-settings.js`
**Interfaces:**
- Consumes: shared runtime/catalogs and updated manifests.
- Produces: complete `dist/chromium` and `dist/firefox` extension directories.
- [ ] **Step 1: Add failing build-content assertions**
Extend `scripts/test-i18n.js` to run after build when `dist` exists and assert
both targets contain:
```text
i18n.js
locales/en.json
locales/ru.json
```
- [ ] **Step 2: Update the build**
For Chromium, concatenate `shared/i18n.js` before `shared/background.js` and
also copy it as `dist/chromium/i18n.js` for popup use. For Firefox, copy
`shared/i18n.js` beside background scripts. Copy both JSON catalogs to each
target's `locales/` directory.
- [ ] **Step 3: Document the selector**
Add a README section stating that popup settings provide persisted
`System / English / Russian`, that System uses browser UI language, and that
extension/desktop preferences are independent.
- [ ] **Step 4: Run complete verification**
```bash
npm test
npm run build
npm test
git diff --check
```
Expected:
- protocol, runtime, popup, and background tests pass;
- both browser distributions build;
- post-build content assertions pass;
- no whitespace errors.
- [ ] **Step 5: Commit packaging and docs**
```bash
git add scripts/build-extension.js README.md scripts/test-i18n.js
git commit -m "build: package browser extension locale catalogs"
```

View File

@ -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 `<select>` with
`system`, `en`, and `ru` options. Selecting a value:
1. updates all popup chrome immediately without reopening the popup;
2. sends the full settings patch to background storage;
3. preserves receiver URL and pairing token values;
4. shows the localized saved/error state.
The `<html lang>` attribute is updated to the resolved locale. User data,
receiver URLs, tokens, file names, and backend-provided error text are not
translated.
## Background and Context Menus
`DEFAULT_SETTINGS` gains `language: "system"`. Context-menu creation resolves
the effective locale from stored settings and creates localized page,
selection, and link titles.
After a language setting is saved, background recreates the context menus so
the new language applies without reinstalling or reloading the extension.
Failure to access the i18n API falls back to English and must not block capture
or settings operations.
## Error Handling
- Missing catalog keys fall back to English, then to the provided literal/key.
- Invalid stored language values behave as `system`.
- Catalog or browser-language detection failure falls back to English.
- Existing receiver and capture errors continue to be shown; known extension
validation/status chrome around them is localized.
## Verification
Tests are written before production changes and cover:
- `ru-*` and non-Russian system-language resolution;
- explicit language override and invalid-preference normalization;
- English/Russian catalog parity and interpolation;
- popup language persistence without losing receiver settings;
- live popup translation after selecting Russian/English;
- localized online/offline/unknown and capture status messages;
- localized context-menu creation and recreation after language changes;
- build contents for both Chromium and Firefox.
Final verification commands:
```bash
npm test
npm run build
```
Manual installation or store signing is outside this milestone.

View File

@ -5,7 +5,7 @@
"description": "Verstak browser capture extension for Chromium and Firefox",
"scripts": {
"build": "node scripts/build-extension.js",
"test": "node scripts/test-protocol.js && node scripts/test-popup-settings.js",
"test": "node scripts/test-protocol.js && node scripts/test-i18n.js && node scripts/test-popup-settings.js",
"sign:firefox": "./scripts/sign-firefox-xpi.sh",
"release:firefox": "./scripts/release-firefox-xpi.sh"
},

45
scripts/test-i18n.js Normal file
View File

@ -0,0 +1,45 @@
#!/usr/bin/env node
const assert = require('assert');
const fs = require('fs');
const path = require('path');
const root = path.resolve(__dirname, '..');
const i18n = require(path.join(root, 'shared', 'i18n.js'));
const en = JSON.parse(fs.readFileSync(path.join(root, 'shared', 'locales', 'en.json'), 'utf8'));
const ru = JSON.parse(fs.readFileSync(path.join(root, 'shared', 'locales', 'ru.json'), 'utf8'));
assert.strictEqual(i18n.normalizePreference(undefined), 'system');
assert.strictEqual(i18n.normalizePreference('de'), 'system');
assert.strictEqual(i18n.normalizePreference('system'), 'system');
assert.strictEqual(i18n.normalizePreference('en'), 'en');
assert.strictEqual(i18n.normalizePreference('ru'), 'ru');
assert.strictEqual(i18n.resolveLocale('system', 'ru'), 'ru');
assert.strictEqual(i18n.resolveLocale('system', 'ru-RU'), 'ru');
assert.strictEqual(i18n.resolveLocale('system', 'RU-ru'), 'ru');
assert.strictEqual(i18n.resolveLocale('system', 'uk-UA'), 'en');
assert.strictEqual(i18n.resolveLocale('system', 'en-US'), 'en');
assert.strictEqual(i18n.resolveLocale('en', 'ru-RU'), 'en');
assert.strictEqual(i18n.resolveLocale('ru', 'en-US'), 'ru');
assert.deepStrictEqual(Object.keys(ru).sort(), Object.keys(en).sort());
assert.ok(Object.values(en).every((value) => typeof value === 'string'));
assert.ok(Object.values(ru).every((value) => typeof value === 'string'));
const tEn = i18n.createTranslator({ en, ru }, 'en');
const tRu = i18n.createTranslator({ en, ru }, 'ru');
assert.strictEqual(tRu('status.queued'), 'В очереди до запуска Верстака');
assert.strictEqual(tEn('error.value', { error: 'offline' }), 'Error: offline');
assert.strictEqual(tRu('missing', null, 'Fallback'), 'Fallback');
assert.strictEqual(tRu('missing.key'), 'missing.key');
i18n.loadCatalogs((locale) => Promise.resolve(locale === 'ru' ? ru : en))
.then((catalogs) => {
assert.strictEqual(catalogs.en, en);
assert.strictEqual(catalogs.ru, ru);
console.log('browser extension localization runtime tests passed');
})
.catch((error) => {
console.error(error);
process.exit(1);
});

54
shared/i18n.js Normal file
View File

@ -0,0 +1,54 @@
(function (root, factory) {
'use strict';
var api = factory();
root.VerstakBrowserI18n = api;
if (typeof module !== 'undefined' && module.exports) module.exports = api;
})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
'use strict';
var PREFERENCES = { system: true, en: true, ru: true };
function normalizePreference(value) {
value = String(value || '').trim().toLowerCase();
return PREFERENCES[value] ? value : 'system';
}
function resolveLocale(preference, systemLocale) {
preference = normalizePreference(preference);
if (preference === 'en' || preference === 'ru') return preference;
systemLocale = String(systemLocale || '').trim().toLowerCase();
return systemLocale === 'ru' || systemLocale.indexOf('ru-') === 0 ? 'ru' : 'en';
}
function interpolate(message, params) {
if (!params) return message;
return message.replace(/\{([A-Za-z0-9_.-]+)\}/g, function (placeholder, name) {
return Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : placeholder;
});
}
function loadCatalogs(loadJSON) {
return Promise.all([loadJSON('en'), loadJSON('ru')]).then(function (catalogs) {
return { en: catalogs[0] || {}, ru: catalogs[1] || {} };
});
}
function createTranslator(catalogs, locale) {
catalogs = catalogs || {};
locale = locale === 'ru' ? 'ru' : 'en';
return function translate(key, params, fallback) {
var message = catalogs[locale] && catalogs[locale][key];
if (message == null && catalogs.en) message = catalogs.en[key];
if (message == null) message = fallback == null ? key : fallback;
return interpolate(String(message), params);
};
}
return {
normalizePreference: normalizePreference,
resolveLocale: resolveLocale,
loadCatalogs: loadCatalogs,
createTranslator: createTranslator
};
});

33
shared/locales/en.json Normal file
View File

@ -0,0 +1,33 @@
{
"popup.subtitle": "Browser Inbox",
"label.receiver": "Receiver",
"label.pending": "Pending",
"label.url": "URL",
"label.file": "File",
"label.receiverUrl": "Receiver URL",
"label.pairingToken": "Pairing token",
"label.language": "Language",
"action.sendPage": "Send Page",
"action.sendFile": "Send File",
"action.retryPending": "Retry Pending",
"action.save": "Save",
"hint.contextMenu": "Selection and link captures are available from the page context menu.",
"receiver.online": "Online",
"receiver.offline": "Offline",
"receiver.unknown": "Unknown",
"language.system": "System",
"language.en": "English",
"language.ru": "Russian",
"status.sending": "Sending...",
"status.queued": "Queued until Verstak is available",
"status.done": "Done",
"status.readingFile": "Reading file...",
"status.saved": "Saved",
"error.chooseFile": "Choose a file first",
"error.fileTooLarge": "File is too large for browser capture",
"error.invalidReceiverUrl": "Receiver URL must start with http:// or https://",
"error.value": "Error: {error}",
"context.sendPage": "Send page to Verstak",
"context.sendSelection": "Send selection to Verstak",
"context.sendLink": "Send link to Verstak"
}

33
shared/locales/ru.json Normal file
View File

@ -0,0 +1,33 @@
{
"popup.subtitle": "Входящие из браузера",
"label.receiver": "Приёмник",
"label.pending": "В очереди",
"label.url": "URL",
"label.file": "Файл",
"label.receiverUrl": "URL приёмника",
"label.pairingToken": "Токен сопряжения",
"label.language": "Язык",
"action.sendPage": "Отправить страницу",
"action.sendFile": "Отправить файл",
"action.retryPending": "Повторить отправку",
"action.save": "Сохранить",
"hint.contextMenu": "Выделение и ссылки можно отправить через контекстное меню страницы.",
"receiver.online": "Доступен",
"receiver.offline": "Недоступен",
"receiver.unknown": "Неизвестно",
"language.system": "Системный",
"language.en": "Английский",
"language.ru": "Русский",
"status.sending": "Отправка...",
"status.queued": "В очереди до запуска Верстака",
"status.done": "Готово",
"status.readingFile": "Чтение файла...",
"status.saved": "Сохранено",
"error.chooseFile": "Сначала выберите файл",
"error.fileTooLarge": "Файл слишком велик для отправки из браузера",
"error.invalidReceiverUrl": "URL приёмника должен начинаться с http:// или https://",
"error.value": "Ошибка: {error}",
"context.sendPage": "Отправить страницу в Верстак",
"context.sendSelection": "Отправить выделение в Верстак",
"context.sendLink": "Отправить ссылку в Верстак"
}