@endora-commerce/mod-i18n 0.100.0

package/dist/manifest.js

@@ -0,0 +1,245 @@
+import { defineModuleManifest, } from '@endora-commerce/contracts';
+/**
+ * Admin UI i18n subsystem — feature 019.
+ *
+ * Platform-internal module (underscore-prefixed exemption per Constitution
+ * Principle VI, alongside `auth` / `example` / `_lifecycle`). Owns the
+ * `translation_bundles` table, the per-language merged-bundle resolver,
+ * the read API consumed by the admin SPA at boot, and the `core`
+ * namespace that holds admin-chrome strings (AppShell, navigation,
+ * login, profile).
+ *
+ * Depends on `_lifecycle` because every module's bundle install / hard-
+ * uninstall is driven by the lifecycle orchestrator's hook surface.
+ */
+export const manifest = defineModuleManifest({
+    id: '_i18n',
+    name: 'Admin UI i18n',
+    // One string literal, not a concatenation: `manifests:generate` reads this
+    // field to render the package's `description`, and it reads a literal — a
+    // package whose description is computed is one the generator refuses rather
+    // than invents a sentence for (feature 080, T041).
+    description: 'Per-user Admin UI language preference and module-scoped translation bundles. English is the platform-wide fallback (FR-013 / FR-016).',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port every route here is gated by;
+    // `admin_users` owns the service the preferred-language setter writes through.
+    // Neither depends back on this module, so the graph stays acyclic.
+    dependencies: ['_lifecycle', 'auth', 'admin_users'],
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    // Feature 074 (Constitution XVII), test C1 — reachability. Two grounds hold
+    // and they are stated in that order because only the first is about this
+    // module's merits: every user-facing string on every surface resolves here,
+    // including the labels on `/platform/modules`, so switching it off would
+    // leave an operator unable to read the screen that switches it back on. The
+    // `_`-prefix rule is the structural second: an `_`-prefixed id is
+    // platform-internal and `assertActivationRules`
+    // (`packages/contracts/src/modules.ts`) refuses any other activation form
+    // for one.
+    activation: {
+        nonDeactivatable: true,
+        reason: 'Every user-facing string on every surface is served from here, including the labels ' +
+            'on the platform screen that holds the module switches.',
+    },
+    /**
+     * **The platform's error-code block — 21 codes, and this is their home** rather
+     * than the residue of a migration (feature 090,
+     * `specs/090-module-owned-error-codes/core-block-home.md`; D-186 §4).
+     *
+     * A code is here because **no module owns its noun** — D-121 T3, and nothing
+     * weaker. Not because the platform throws it: D-121 rejected the thrower rule
+     * by measurement, and four of the entries below name a code exactly one module
+     * raises. Each carries its tier and the sentence that argues it in
+     * `PLATFORM_OWNED_ERROR_CODES`
+     * (`backend/test/fixtures/error-code-routing/reference-ledgers.ts`), which is
+     * where a reason can live in a form a test reads — a comment does not survive
+     * `tsc`, and the gate reads this list out of the built package.
+     *
+     * **The gate, and what it is derived from.**
+     * `backend/test/unit/_i18n/platform-error-code-block.test.ts` holds this list
+     * and those annotations equal in **both** directions: a code added here with no
+     * reason of its own is `unannotated` and names itself, and an annotation this
+     * list no longer backs is `undeclared`. Neither side is a written-down list of
+     * twenty-one (D-100) — the annotations' membership is itself held against
+     * `intendedRouting(capture, ledgers)`, the frozen chain capture with the
+     * re-homing and minting ledgers laid over it, so what belongs here is the
+     * hundred the deleted chain answered `core` for minus the seventy-nine D-129's
+     * sweep moved. D-186 §4 chose that over a scanner because both scanners were
+     * measured and both are ledgers of exceptions (`d129-sweep.md` §6.1–§6.2),
+     * and because a block of twenty-one lines is one a reviewer reads in full.
+     *
+     * **How it came to be twenty-one.** The list opened as the frozen chain
+     * capture and not as a judgement: the verbatim output of the runbook's step-1
+     * derivation over `test/fixtures/error-code-routing/chain-answers.ts`, every
+     * code `moduleIdForErrorCode` answered `core` for, because
+     * `contracts/error-code-declaration.md` §6.2 makes the migration
+     * answer-preserving over all 289 codes with no exception list and §6.5 puts
+     * re-routing out of scope. Most of that hundred was never the platform's: they
+     * fell off the end of a prefix chain that ended in `return 'core'`, which is
+     * the defect `specs/082-error-code-ownership/rulings.md` §9 opened the sweep
+     * for. D-129's sweep then moved **79 codes into 20 modules** over six batches —
+     * Tier A's `KSEF_*` and `PIM_ERGONODE_*` (MR 2) and its six remaining modules
+     * (MR 3), Tier B's six that already shipped a bundle (MR 4) and its four that
+     * had to create one (MR 5), then Tier C's `admin_roles` (MR 6) and
+     * `organizations` (MR 7) — and every one of the 79 carries a
+     * `REHOMED_ERROR_CODES` entry naming where it went, which tier decided it and
+     * why. The capture itself is untouched, because a reference a migration may
+     * rewrite is one that agrees with whatever the migration did.
+     *
+     * **Do not move one in passing.** A code that leaves this list without arriving
+     * in its owner's manifest routes nowhere; one that arrives in both routes to
+     * neither, and the collision rule makes that visible at composition rather than
+     * at an operator. The three ledgers and the two harnesses all read the same
+     * reference, so a half-done move is red in the merge request that made it.
+     *
+     * **Why `_i18n` and not a module called `core`.** `core` is not a module id. It
+     * is the synthetic namespace this module's bundle is exposed under at the
+     * resolver boundary (`I18N_CHROME_MODULE_ID` / `CORE_NAMESPACE` in
+     * `backend/services/i18n-service.ts`), so the module that owns the platform
+     * bundle — the phrase §6.5 uses — is this one. Every sentence for these codes
+     * already lives in this package's `i18n/{en,pl}.json`. The alternatives, and
+     * why each was refused, are §4 of the design note: a residual set in
+     * `packages/contracts` (a second input to a derivation §4 says has one),
+     * `_lifecycle` (82 sentence keys moved for no operator-visible gain), and a new
+     * registered `_platform` module (a registry row, an install-order position and
+     * a `/platform/modules` row, invented to hold a list).
+     *
+     * **`tokens` is derived from the raise sites, not from the bundle** (runbook
+     * §5), and the arithmetic below is **re-derived on this tree rather than
+     * decremented** — which is the instruction each batch of the sweep followed and
+     * the reason the numbers survived it. Measured over the 21 by balanced-paren
+     * extraction of every `new HttpError(...)` call's own arguments: **794 raise
+     * sites, four of the codes carrying a `details.code`**. Three of the four
+     * declare their tokens here — five tokens in total, of which **two have a
+     * sentence in both languages** (`FORBIDDEN.organization_cannot_transact`,
+     * `.customer_outside_assignment_scope`) and three do not, each of those three
+     * being a Phase 4 finding rather than a silent absence. The fourth is
+     * `VALIDATION_FAILED`, which declares **none** although 19 distinct tokens are
+     * passed at its raise sites: `localizeErrorEnvelope` returns before translating
+     * that code (`packages/platform/src/http/error-envelope.ts`), so its
+     * `details.code` values are machine-readable discriminators on the wire and can
+     * never key an `errors.VALIDATION_FAILED.<token>` sentence. Declaring them
+     * would declare sentences nothing can render. If a code arrives or leaves,
+     * re-run the scan; do not adjust the number.
+     *
+     * **What the bundle holds for these 21**: 16 `errors.*` keys in each language —
+     * 14 base sentences and the two token keys above. The seven codes with no
+     * sentence are the six `MODULE_*` refusals an operator meets through the
+     * lifecycle CLI rather than through the envelope, plus `PRICE_UNAVAILABLE`,
+     * which nothing raises. All seven are on `UNTRANSLATED_ERROR_CODES` under this
+     * module's group and are drained by writing a sentence, never by moving a code.
+     */
+    errorCodes: [
+        // T3 — the platform's own `MODULE_*` vocabulary (7). The noun is a module,
+        // and what installs, composes, gates and withdraws one is the platform.
+        // `settings`, `audit_logs`, `product_feeds` and `carts` raise four of these
+        // seven and own none of them; the deleted chain reached them through a rule
+        // that **named** them (`startsWith('MODULE_')`), which is a decision rather
+        // than the fall-through the rest of the block arrived by (`d129-sweep.md`
+        // §2.2).
+        { code: 'MODULE_ACTIVATION_PROTECTED' },
+        { code: 'MODULE_DEPENDENCIES_ABSENT' },
+        { code: 'MODULE_DEPENDENTS_PRESENT' },
+        { code: 'MODULE_DISABLED' },
+        { code: 'MODULE_NOT_DEACTIVATABLE' },
+        { code: 'MODULE_NOT_FOUND' },
+        { code: 'MODULE_SETTING_READ_ONLY' },
+        // T3 — the envelope's generic vocabulary (6). Each of these is what dozens
+        // of modules answer with for a condition that is about the request rather
+        // than about a noun, so its sentence has to be generic and the specific case
+        // is a token on it (issue #65) or an interpolated value (issue #161).
+        { code: 'FORBIDDEN', tokens: [
+                'organization_cannot_transact',
+                'customer_outside_assignment_scope',
+                'reorder_disabled',
+            ] },
+        { code: 'INTERNAL', tokens: ['customer_account_organization_missing'] },
+        { code: 'NOT_FOUND' },
+        { code: 'UNAUTHORIZED' },
+        { code: 'VALIDATION_FAILED' },
+        { code: 'VERSION_CONFLICT', tokens: ['organization_version_mismatch'] },
+        // T3 by D-122 — a noun with two claimants or none (7). Identical claimants
+        // are the proof: `admin_users` and `customer_accounts` each own an account
+        // with a password, `orders` and `returns` each own a state machine, and
+        // `catalog` and `price_lists` both claim the noun "price".
+        // `INVALID_TRANSITION` is the code D-122 was written about.
+        { code: 'CURRENT_PASSWORD_INVALID' },
+        { code: 'EMAIL_ALREADY_REGISTERED' },
+        { code: 'INVALID_CREDENTIALS' },
+        { code: 'INVALID_TRANSITION' },
+        { code: 'PRICE_UNAVAILABLE' },
+        { code: 'TERMS_VERSION_STALE' },
+        { code: 'TOKEN_INVALID_OR_EXPIRED' },
+        // T3 by declaration (1). The deleted chain named `RATE_LIMITED` in an
+        // explicit generic list rather than reaching it by fall-through, which makes
+        // it `core-block-home.md` §1.3's counter-example: an explicit T3 with one
+        // raiser today. The noun is a request budget, which the platform imposes.
+        { code: 'RATE_LIMITED' },
+    ],
+});
+/**
+ * `translation_bundles` follows the manifest set — feature 080, T036a / D-159.
+ *
+ * Not an install hook: an install hook fires for *its own* module, and this has
+ * to run whenever **any** module is installed, because this module's table is a
+ * projection of every other module's `manifest.i18n` declaration. Not a port
+ * either: the lifecycle orchestrator also serves the five `module:*` commands,
+ * and a platform command composes no container to resolve one from (D-157.2 /
+ * D-157.4) — which is exactly how a terminal install came to write no bundle at
+ * all while the same install from `/platform/modules` wrote them.
+ *
+ * The service is imported at call time, not at module load. This file is
+ * imported by the generated manifest index, which is in turn imported by every
+ * static check script and by `src/db/configured-migrations.ts`; a static import
+ * of `I18nService` would pull an ORM-dependent graph into all of them.
+ *
+ * A fresh `I18nService` per call is correct and not a lost cache:
+ * `getMergedBundleForLanguage` revalidates against `MAX(version)` in the table
+ * on every read, so the running server picks the new rows up on its next
+ * request without having been the instance that wrote them.
+ */
+export const lifecycleParticipant = {
+    async onModuleInstalled({ moduleId, manifest: installed, modulePath, em }) {
+        // The declaration belongs to the module being installed, so the decision
+        // is this one's to make: a manifest with no `i18n` block ships no bundle.
+        if (!installed.i18n)
+            return;
+        const { I18nService } = await import('./backend/services/i18n-service.js');
+        await new I18nService({ em: () => em }).installBundlesForModule(moduleId, modulePath, installed.i18n.bundlesDir, em);
+    },
+    async onModuleHardUninstalled({ moduleId, em }) {
+        // Unconditional, and deliberately not gated on the manifest's `i18n`
+        // block: the manifest is `null` for an orphan row whose module this
+        // instance no longer has, and that is the one case whose rows nothing
+        // else will ever remove.
+        const { I18nService } = await import('./backend/services/i18n-service.js');
+        await new I18nService({ em: () => em }).removeBundlesForModule(moduleId, em);
+    },
+};
+/**
+ * The two operator commands this module declares — feature 080, T042b /
+ * D-160.9.
+ *
+ * They were `scripts/reload.ts` and `scripts/coverage.ts`, each opening its own
+ * ORM and building its own `I18nService`. The host composes now and hands the
+ * body this module's `ModuleContext`, which is what retired this module's one
+ * `check:module-boundary` key: `reload` needed the deployment's module registry,
+ * and the registry is a root-supplied name any module may read off its cradle.
+ *
+ * The bodies are `await import()`ed for the reason the participant above gives:
+ * this file is imported by the generated manifest index, and through it by every
+ * static check script and by `src/db/configured-migrations.ts`.
+ */
+export const cliCommands = [
+    {
+        name: 'reload',
+        summary: "Re-read every module's on-disk i18n bundles into translation_bundles.",
+        run: async (context) => (await import('./backend/cli/reload.js')).reload(context),
+    },
+    {
+        name: 'coverage',
+        summary: 'Print the per-module, per-language translation coverage snapshot.',
+        run: async (context) => (await import('./backend/cli/coverage.js')).coverage(context),
+    },
+];
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/migrations/20260507T091405_i18n_admin_i18n_init.d.ts

@@ -0,0 +1,30 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Admin UI language versions — feature 019 / data-model.md §1.
+ *
+ * Schema changes (one atomic migration):
+ *   - new sequence `translation_bundles_version_seq` — monotonically-
+ *     increasing version vector consumed by the resolver's cache
+ *     invalidation path (research §R9).
+ *   - new table `translation_bundles` — one row per
+ *     `(module_id, language_code)`. JSONB `entries` carries the flat
+ *     translation key → string map; `version` defaults to
+ *     `nextval(translation_bundles_version_seq)` so every UPSERT bumps
+ *     the vector without explicit application logic.
+ *   - btree index `idx_translation_bundles_language_code` to support
+ *     `GET /api/v1/admin/i18n/bundles?language=…` which scans by language.
+ *   - column `admin_users.preferred_language` (nullable) — NULL means
+ *     "no preference saved", which the resolver treats as `'en'`
+ *     (feature 019 spec FR-003 / FR-016).
+ *
+ * No FK on `translation_bundles.module_id`: modules are filesystem-driven
+ * (feature 018) and `module_registrations` is the registry of record;
+ * adding a FK here would couple lifecycle ordering in ways the existing
+ * modules do not have. Cleanup is enforced by the lifecycle hard-uninstall
+ * hook, not by ON DELETE CASCADE.
+ */
+export declare class Migration20260507T091405I18nAdminI18nInit extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260507T091405_i18n_admin_i18n_init.d.ts.map

package/dist/migrations/20260507T091405_i18n_admin_i18n_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260507T091405_i18n_admin_i18n_init.d.ts","sourceRoot":"","sources":["../../src/migrations/20260507T091405_i18n_admin_i18n_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,yCAA0C,SAAQ,SAAS;IACvD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAKrC"}

package/dist/migrations/20260507T091405_i18n_admin_i18n_init.js

@@ -0,0 +1,50 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Admin UI language versions — feature 019 / data-model.md §1.
+ *
+ * Schema changes (one atomic migration):
+ *   - new sequence `translation_bundles_version_seq` — monotonically-
+ *     increasing version vector consumed by the resolver's cache
+ *     invalidation path (research §R9).
+ *   - new table `translation_bundles` — one row per
+ *     `(module_id, language_code)`. JSONB `entries` carries the flat
+ *     translation key → string map; `version` defaults to
+ *     `nextval(translation_bundles_version_seq)` so every UPSERT bumps
+ *     the vector without explicit application logic.
+ *   - btree index `idx_translation_bundles_language_code` to support
+ *     `GET /api/v1/admin/i18n/bundles?language=…` which scans by language.
+ *   - column `admin_users.preferred_language` (nullable) — NULL means
+ *     "no preference saved", which the resolver treats as `'en'`
+ *     (feature 019 spec FR-003 / FR-016).
+ *
+ * No FK on `translation_bundles.module_id`: modules are filesystem-driven
+ * (feature 018) and `module_registrations` is the registry of record;
+ * adding a FK here would couple lifecycle ordering in ways the existing
+ * modules do not have. Cleanup is enforced by the lifecycle hard-uninstall
+ * hook, not by ON DELETE CASCADE.
+ */
+export class Migration20260507T091405I18nAdminI18nInit extends Migration {
+    async up() {
+        this.addSql(`create sequence "translation_bundles_version_seq" as bigint;`);
+        this.addSql(`
+      create table "translation_bundles" (
+        "module_id" varchar(64) not null,
+        "language_code" varchar(12) not null,
+        "entries" jsonb not null default '{}'::jsonb,
+        "version" bigint not null default nextval('translation_bundles_version_seq'),
+        "installed_at" timestamptz not null default now(),
+        "updated_at" timestamptz not null default now(),
+        constraint "translation_bundles_pkey" primary key ("module_id", "language_code")
+      );
+    `);
+        this.addSql(`alter sequence "translation_bundles_version_seq" owned by "translation_bundles"."version";`);
+        this.addSql(`create index "idx_translation_bundles_language_code" on "translation_bundles" ("language_code");`);
+        this.addSql(`alter table "admin_users" add column "preferred_language" varchar(12) null;`);
+    }
+    async down() {
+        this.addSql(`alter table "admin_users" drop column if exists "preferred_language";`);
+        this.addSql(`drop table if exists "translation_bundles";`);
+        this.addSql(`drop sequence if exists "translation_bundles_version_seq";`);
+    }
+}
+//# sourceMappingURL=20260507T091405_i18n_admin_i18n_init.js.map

package/dist/migrations/20260507T091405_i18n_admin_i18n_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260507T091405_i18n_admin_i18n_init.js","sourceRoot":"","sources":["../../src/migrations/20260507T091405_i18n_admin_i18n_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,yCAA0C,SAAQ,SAAS;IAC7D,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC,8DAA8D,CAAC,CAAC;QAE5E,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;KAUX,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CACT,4FAA4F,CAC7F,CAAC;QAEF,IAAI,CAAC,MAAM,CACT,kGAAkG,CACnG,CAAC;QAEF,IAAI,CAAC,MAAM,CACT,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,uEAAuE,CAAC,CAAC;QACrF,IAAI,CAAC,MAAM,CAAC,6CAA6C,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,4DAA4D,CAAC,CAAC;IAC5E,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * **One class**, and it creates the `translation_bundles` table together with
+ * the `translation_bundles_version_seq` sequence the resolver's cache
+ * invalidation reads. Its position relative to every other module's is decided
+ * by the manifest `dependencies` graph (feature 081); the timestamp orders this
+ * module's own migrations and nothing else.
+ *
+ * The **named** export stays beside the array. `db/migrations-registry.generated.ts`
+ * imports the class by name from this specifier, and a migration class name is
+ * contract in a way an entity class name is not: `mikro_orm_migrations` persists
+ * it, so it is a string every already-migrated database holds.
+ */
+import { Migration20260507T091405I18nAdminI18nInit } from './20260507T091405_i18n_admin_i18n_init.js';
+export declare const migrations: (typeof Migration20260507T091405I18nAdminI18nInit)[];
+export { Migration20260507T091405I18nAdminI18nInit };
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,yCAAyC,EAAE,MAAM,2CAA2C,CAAC;AAEtG,eAAO,MAAM,UAAU,sDAA8C,CAAC;AAEtE,OAAO,EAAE,yCAAyC,EAAE,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,23 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * **One class**, and it creates the `translation_bundles` table together with
+ * the `translation_bundles_version_seq` sequence the resolver's cache
+ * invalidation reads. Its position relative to every other module's is decided
+ * by the manifest `dependencies` graph (feature 081); the timestamp orders this
+ * module's own migrations and nothing else.
+ *
+ * The **named** export stays beside the array. `db/migrations-registry.generated.ts`
+ * imports the class by name from this specifier, and a migration class name is
+ * contract in a way an entity class name is not: `mikro_orm_migrations` persists
+ * it, so it is a string every already-migrated database holds.
+ */
+import { Migration20260507T091405I18nAdminI18nInit } from './20260507T091405_i18n_admin_i18n_init.js';
+export const migrations = [Migration20260507T091405I18nAdminI18nInit];
+export { Migration20260507T091405I18nAdminI18nInit };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,yCAAyC,EAAE,MAAM,2CAA2C,CAAC;AAEtG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,yCAAyC,CAAC,CAAC;AAEtE,OAAO,EAAE,yCAAyC,EAAE,CAAC"}

package/docs/i18n.md

@@ -0,0 +1,166 @@
+---
+title: Admin UI Languages
+description: Admin UI per-user language preference + module-scoped translation bundles
+---
+
+# Admin UI Languages
+
+Per-user language preference for the Admin UI plus a module-scoped translation pipeline that
+lets every backend module ship its own bundle of translated strings. Polish and English are
+shipped at launch; English is the platform-wide fallback.
+
+The subsystem itself is the workspace package `@endora-commerce/mod-i18n`, at
+`packages/modules/_i18n/` (platform-internal — leading underscore, which the npm name drops).
+Its translation bundles sit at the package root, `packages/modules/_i18n/i18n/`, because the
+platform anchors a module's `bundlesDir` to the module's own directory and a package's own
+directory is where its `package.json` is. The admin SPA's runtime lives at `admin/src/i18n/`.
+
+## How a user changes their language
+
+1. Sign in to the Admin UI.
+2. Open the **Profile** page (top-right avatar, or the `EN` / `PL` badge in the topbar).
+3. Pick **English** or **Polski** in the **Language** section, then click **Save language**.
+4. The whole Admin UI re-renders in the chosen language. No sign-out is required.
+
+The choice is persisted on the user's record and follows the user across devices: signing in
+from a different browser or machine yields the same Admin UI language as the most recent
+saved choice.
+
+New users (and users who have never made a choice) see English by default.
+
+## Public surface
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `GET /api/v1/admin/i18n/bundles?language=<en\|pl>` | Returns the merged `core` + per-module bundle for the requested language plus a monotonically-non-decreasing `version` vector the SPA uses to detect refreshes. Permission: any authenticated admin. |
+| `PATCH /api/v1/admin/me/preferred-language` | Sets the calling user's preferred language. Body: `{ "preferredLanguage": "en" \| "pl" \| null }`. Idempotent; `null` reverts to "no preference saved" → English fallback. Permission: any authenticated admin. |
+
+The session-bootstrap response (`GET /api/v1/admin/me`) carries `preferredLanguage` in the
+`adminUser` object so the SPA can seed its `<TranslationProvider>` without an extra round-trip.
+
+## How a module ships translations
+
+1. Declare the bundle directory in your manifest:
+
+   ```typescript
+   // packages/modules/<my_module>/src/manifest.ts
+   import { defineModuleManifest } from '@endora-commerce/contracts';
+
+   export const manifest = defineModuleManifest({
+     id: 'my_module',
+     name: 'My module',
+     version: '1.0.0',
+     dependencies: [],
+     i18n: { bundlesDir: 'i18n' }, // ← add this
+   });
+   ```
+
+2. Author per-language JSON files at `packages/modules/<my_module>/i18n/<lang>.json` —
+   the package root, not under `src/`, because `bundlesDir` is resolved against the
+   directory holding the module's `package.json`.
+   The shape is a flat `Record<string, string>` — keys are dotted (`"actions.save"`),
+   values are strings. `{name}`-style placeholders are interpolated at runtime.
+
+   ```jsonc
+   // packages/modules/my_module/i18n/en.json
+   {
+     "actions.save": "Save",
+     "validation.required": "This field is required.",
+     "audit.userCreated": "Created user \"{email}\"."
+   }
+   ```
+
+3. Replace inline strings in the admin code with `useTranslation(scope)` calls:
+
+   ```tsx
+   import { useTranslation } from '@/i18n/useTranslation';
+
+   export function MyForm() {
+     const t = useTranslation('my_module');
+     return <button>{t('actions.save')}</button>;
+   }
+   ```
+
+4. Restart (or re-install) the backend. The boot-time bundle reconciler walks every module
+   declaring `manifest.i18n` and refreshes its `translation_bundles` rows from the JSON files
+   on disk. Failures are logged but do not abort boot.
+
+### Rules and constraints
+
+- The supported set is currently `['en', 'pl']` (closed enum in `@endora-commerce/contracts/src/admin-i18n.ts`).
+- Files for unsupported languages are rejected at install time.
+- A module that ships any bundle MUST ship `en.json` (English is the platform-wide fallback).
+  A Polish bundle is encouraged but optional — ship it in the same PR as the English file.
+- Two modules MAY use the same key string (for example `actions.save`); each bundle is scoped
+  to its owning module so the strings do not collide.
+- User-authored content (CMS pages, product names, blog posts, setting *values*) is **out of
+  scope** for this feature — it is rendered as authored, not re-translated.
+
+## How the resolver picks a string
+
+Every lookup goes through a three-step fallback chain:
+
+1. The user's preferred-language entry under the module's scope.
+2. The English entry under the module's scope.
+3. A literal placeholder `${scope}.${key}` (always non-empty so the UI never goes blank).
+
+Both the backend resolver (`I18nService.translate(...)`) and the admin SPA resolver
+(`admin/src/i18n/resolver.ts`) share the same chain.
+
+## Diagnosing missing translations
+
+When the resolver falls back, the backend writes a structured log line through the platform's
+existing logger:
+
+```json
+{ "event": "i18n.fallback", "moduleId": "settings", "languageCode": "pl", "key": "actions.save", "fellBackTo": "en" }
+```
+
+Operators can answer "what's missing in our Polish bundle?" with a single grep:
+
+```bash
+grep '"event":"i18n.fallback"' /var/log/b2b-backend.log | jq -r '"\(.languageCode) \(.moduleId).\(.key) → \(.fellBackTo)"' | sort -u
+```
+
+The admin SPA emits the same gap as a `console.warn` in development (`import.meta.env.DEV`)
+and is silent in production.
+
+## Database
+
+One MikroORM migration (`040_admin_i18n_init.ts`) introduces:
+
+- Sequence `translation_bundles_version_seq` (the cache-invalidation vector).
+- Table `translation_bundles` — one row per `(module_id, language_code)`, JSONB `entries`,
+  `version` defaults to `nextval(translation_bundles_version_seq)` so every UPSERT advances
+  the sequence.
+- Column `admin_users.preferred_language` (varchar(12), nullable). NULL means "no preference
+  saved" → resolver treats as English.
+
+No FK on `translation_bundles.module_id` — modules are filesystem-driven and the
+hard-uninstall hook is the cleanup mechanism, not `ON DELETE CASCADE`.
+
+## Adding a third language
+
+Adding `de` (or any other BCP-47 code) is treated as a separate feature because the cost is
+mostly translation work, not engineering. The schema change is one line in
+`@endora-commerce/contracts/src/admin-i18n.ts`:
+
+```typescript
+export const SupportedAdminLanguageSchema = z.enum(['en', 'pl', 'de']);
+```
+
+After that, each module that emits admin-visible strings must ship `de.json` (or accept the
+EN fallback). The Profile page's selector picks up the new code automatically.
+
+## Testing
+
+Unit tests live next to the implementation:
+
+- `backend/test/unit/_i18n/bundle-loader.unit.test.ts` — every `BundleLoadError` reason path
+  (parse-failed, invalid-shape, unsupported-language-file, missing-fallback-bundle) plus the
+  happy path and EN-only acceptance.
+- `backend/test/unit/_i18n/missing-key-logger.unit.test.ts` — structured log line shape.
+- `backend/test/unit/_i18n/i18n-service.unit.test.ts` — the three-step fallback chain plus
+  interpolation.
+- `admin/test/i18n/resolver.test.ts` — the same chain on the SPA side.
+- `admin/test/i18n/interpolate.test.ts` — placeholder regex.