@vtex/faststore-plugin-buyer-portal 2.0.13 → 2.0.14

package/specs/custom-localization-system.md

@@ -0,0 +1,711 @@
+# Custom Localization System
+
+> **Status**: Done
+> **Created**: 2026-06-01
+
+## 1. Business Context
+
+### Problem Statement
+
+The Buyer Portal plugin currently ships with hardcoded UI strings spread across
+components, layouts, and route configuration. There is no centralized mechanism to
+deliver translated labels, and no dependency-free way to fetch them from VTEX's
+content platform.
+
+We need a **custom, dependency-free localization system** that:
+
+- Fetches translated labels over HTTP from the VTEX content-platform localization endpoint.
+- Loads those labels **strictly server-side**, inside the `loader` of files under
+  `src/pages/`, so no extra client round-trips happen.
+- Exposes a simple `t()` translation function to any component without prop drilling.
+- Adds **zero external runtime dependencies** (no `react-i18next`, `i18next`, etc.).
+
+This affects every B2B buyer/administrator using the portal: their UI must render
+localized labels, starting with English (the only locale today), while keeping the
+architecture ready for additional locales later.
+
+### Goals
+
+- Centralize all translatable labels behind a single `t(key, interpolations?)` function.
+- Fetch labels once per page, server-side, in the page loader.
+- Achieve O(1) label lookup at render time (no array `.find()` per call).
+- Provide graceful fallback: an unknown key returns the key itself (never crashes, never blank).
+- Support index-based interpolation (`{0}`, `{1}`, …).
+- Keep the plugin boundary intact and ship zero new runtime dependencies (FR-010).
+
+### User Stories
+
+#### US-1: Translate a static label
+
+- **Story**: As a buyer-portal developer, I want to call `t("feature.group.name")` in a
+  component, so that I render the translated string without importing the labels manually.
+- **Acceptance Criteria**:
+  - **Given** the page loader fetched labels containing `feature.group.name`, **when** a
+    child component calls `t("feature.group.name")`, **then** it returns the translated value.
+  - **Given** the key does not exist in the loaded labels, **when** the component calls
+    `t("feature.group.name")`, **then** it returns the literal string `"feature.group.name"`.
+
+#### US-2: Interpolate runtime values
+
+- **Story**: As a developer, I want `t()` to substitute positional placeholders, so that I
+  can compose dynamic strings like pagination counters or sentences with embedded links.
+- **Acceptance Criteria**:
+  - **Given** the label `shared.pagination.label` = `"De {0} a {1} itens de {2}"`, **when** I
+    call `t("shared.pagination.label", [1, 25, 100])`, **then** it returns `"De 1 a 25 itens de 100"`.
+  - **Given** a placeholder index has no matching interpolation value, **when** `t()` runs,
+    **then** the placeholder token is left untouched in the output.
+  - **Given** more interpolations than placeholders are passed, **when** `t()` runs, **then**
+    the extra values are ignored and no error is thrown.
+  - **Given** at least one interpolation value is a React node (e.g. a JSX element), **when** I
+    call `t("key", [<a key="x">Name</a>])`, **then** it returns a `ReactNode` array of
+    alternating text segments and the supplied nodes, ready to render inside JSX without manual
+    string splitting.
+
+#### US-3: Load labels server-side per feature
+
+- **Story**: As a developer, I want each page loader to declare which feature entry it needs,
+  so that labels are fetched on the server and injected into the page once.
+- **Acceptance Criteria**:
+  - **Given** a page loader references a feature `ENTRY_ID`, **when** the loader runs on the
+    server, **then** it performs a single GET to the localization endpoint and returns a Key-Value map.
+  - **Given** the localization request fails, **when** the loader resolves, **then** the page still
+    renders and `t()` falls back to returning keys (no thrown error, no blank page).
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — translate + interpolate | Loader fetched labels for the feature | Component calls `t("shared.pagination.label", [1, 25, 100])` | Returns `"De 1 a 25 itens de 100"` |
+| Happy path — ReactNode interpolation | Loader fetched labels; template has a `{0}` placeholder | Component calls `t("msg", [<a key="x">Name</a>])` | Returns `["Click ", <a>Name</a>, " here"]`; renders inline without manual split |
+| Error case — localization request fails | Endpoint returns 5xx / network error | Loader resolves; component calls `t("any.key")` | Page renders; `t("any.key")` returns `"any.key"` |
+| Edge case — missing key | Labels loaded but key absent | Component calls `t("unknown.key")` | Returns `"unknown.key"` (the key itself) |
+| Edge case — placeholder without value | Label `"Hello {0} {1}"`, call `t(key, ["world"])` | `t()` runs | Returns `"Hello world {1}"` (untouched token) |
+
+### Functional Requirements
+
+- **FR-001**: Fetch labels via `GET https://vtex.vtexcommercestable.com.br/api/content-platform/data/vtex/b2b/{LOCALIZATION_CONTENT_TYPE}/entries/{ENTRY_ID}?locale={LOCALE}`. The content type slug (`LOCALIZATION_CONTENT_TYPE`, default `"i18n"`) is configurable in `constants.ts` and must match the CMS content type (see `cms_content_type__i18n.jsonc`).
+- **FR-002**: `ENTRY_ID` values are stored internally as an immutable map (`as const`), keyed by feature.
+- **FR-003**: `LOCALE` is sourced from the browser/request context (`data.locale`) and forwarded by every page loader. When absent, an empty string is passed as fallback — the CMS is responsible for returning the appropriate language for each locale value.
+- **FR-004**: On response, convert `LocalizationLocaleDataType.labels` (an array) into a flat `Record<string, string>` (`LabelMap`) indexed by `key` — done **once**, not per render.
+- **FR-005**: `locale_metadata` must be fully typed but is not consumed yet.
+- **FR-006**: Provide an overloaded `t()` with two call signatures (see Decision 8):
+  - `t(key, (string | number)[]) → string` — pure text interpolation via `String.replace`.
+  - `t(key, ReactNode[]) → ReactNode` — node interpolation; returns a `ReactNode[]` of alternating text segments and the supplied nodes.
+- **FR-007**: `t()` returns the key itself when the key is not found (fallback).
+- **FR-008**: `t()` supports index-based interpolation (`{0}`, `{1}`, …).
+- **FR-009**: Labels are loaded **only** in page loaders (server-side), then injected into the page.
+- **FR-010**: No new external runtime dependencies.
+- **FR-011**: A clear separation between a `Client` (HTTP) and a `Service` (orchestration/transform) layer, matching existing conventions.
+- **FR-012**: The service accepts a **params object** `{ entryIds, locale? }` where `entryIds` is a single entry ID or an array of entry IDs; it merges their maps, always including the `shared` entry automatically so common labels are available on every page without per-loader boilerplate.
+- **FR-013**: On a failed fetch the service logs an **error** through the existing OTLP logger and still returns `{}` (the page never breaks).
+- **FR-014**: The `LocalizationClient` does **not** forward the host-store auth cookie/credentials — labels are treated as public/global content, enabling a shared process-local cache across users.
+
+### Non-Functional Requirements
+
+- **Performance**: Label lookup is O(1) (object access). The array→map transform happens once per `(entryId, locale)`. A **process-local, permanent in-memory cache** (`Map<string, LabelMap>`) plus single-flight (`Map<string, Promise<LabelMap>>`) avoids duplicate fetches. Cache has **no TTL** — updated translations propagate on process restart/deploy (accepted trade-off).
+- **Resilience**: A failed localization fetch must degrade gracefully (empty `LabelMap`, fallback to keys), log an error, and must never break the host store build or the page render.
+- **Plugin boundary**: All code lives under `src/features/shared/localization/` (cross-domain shared utility). No host-store assumptions, no new routes required.
+- **Type safety**: Strict mode, zero `tsc --noEmit` errors, no unjustified `any` (Constitution §III).
+- **Tests**: Unit tests for the transform, `t()` interpolation, and fallback (Constitution §IV).
+
+### Out of Scope
+
+- Runtime locale switching on the client (the spec explicitly states no client-side reactivity is needed).
+- Pluralization, gender, ICU MessageFormat, date/number formatting from `region` metadata.
+- Persisting labels in any client-side storage (localStorage/cookies) or a database.
+- Locale detection/negotiation (locale is empty/default for now).
+- Translating the labels themselves — this system only consumes what the content platform returns.
+- **Migrating existing hardcoded strings** (route titles, buttons, etc.) to `t()`. This work delivers the **mechanism only** (Client/Service/Provider/`t`/types/constants) plus one loader example and one component example. Migrating screens is incremental follow-up work, done per domain in later PRs.
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+A four-layer, dependency-free localization module under `src/features/shared/localization/`:
+
+1. **Constants & Types** — immutable `LOCALIZATION_ENTRY_IDS` map (`as const`), configurable
+   `LOCALIZATION_CONTENT_TYPE` slug (used to build `LOCALIZATION_BASE_URL`), plus the response
+   types from the API contract and the internal `LabelMap` shape.
+2. **Client (`LocalizationClient`)** — extends the existing base `Client`, but targets the
+   content-platform base URL. One method: `getEntry(entryId, locale)`.
+3. **Service (`getLocalizationLabelsService`)** — accepts a params object `{ entryIds, locale? }` with one or many entry IDs (always merging the
+   `shared` entry), calls the client per entry, transforms each `labels[]` into a flat
+   `LabelMap`, merges them, applies a permanent process-local cache + single-flight, logs an
+   error and returns `{}` on failure (never throws).
+4. **Delivery (Context + `t` factory + hook)** — the loader returns the `LabelMap` in the
+   page `context`; a `LocalizationProvider` (placed in the `withProviders` chain **outside**
+   `BuyerPortalProvider`) puts it in a dedicated React Context; components read it via
+   `useLocalization()`, which returns a memoized `t`.
+
+The `t` logic (fallback + interpolation) is a **pure function** factory:
+`createLocalize(labels) => t`. This makes it trivially unit-testable and reusable both
+inside React (via the hook) and outside (e.g. in non-component utilities, by passing the map).
+
+### Architecture Overview
+
+```mermaid
+sequenceDiagram
+    participant Loader as Page loader (SSR)
+    participant Service as getLocalizationLabelsService
+    participant Client as LocalizationClient
+    participant API as content-platform API
+    participant Provider as LocalizationProvider (Context)
+    participant Comp as Child component
+
+    Loader->>Service: getLocalizationLabelsService({ entryIds: ENTRY_ID, locale })
+    Service->>Client: getEntry(entryId, locale)
+    Client->>API: GET .../entries/{ENTRY_ID}?locale={LOCALE}
+    API-->>Client: LocalizationLocaleDataType { locale_metadata, labels[] }
+    Client-->>Service: LocalizationLocaleDataType
+    Service->>Service: labels[] → LabelMap (Record<key,value>)
+    Service-->>Loader: LabelMap (or {} on error)
+    Loader-->>Provider: context.localization.labels (injected into page props)
+    Provider->>Provider: createLocalize(labels) → t (memoized)
+    Comp->>Provider: useLocalization()
+    Provider-->>Comp: { t }
+    Comp->>Comp: t("key", [string|number]) → string OR t("key", [ReactNode]) → ReactNode[]
+```
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| **A. React Context + `t` factory (chosen)** | SSR-safe (per-request value, no cross-request leak); matches existing `BuyerPortalContext` pattern; no prop drilling; testable pure `t` | Components must be inside the provider tree | **Accepted** |
+| B. Module-level mutable singleton store as the source of truth | `t()` callable anywhere without React | On the Next.js server a module singleton is shared across requests → cross-tenant label contamination; needs careful hydration guards | Rejected as the primary store (kept only as an optional client-only read-through, see Decision 3) |
+| C. Pass `labels`/`t` as props down the tree | Explicit, no context | Heavy prop drilling across deep layouts; error-prone | Rejected |
+| D. Use `react-i18next` / `i18next` | Mature, batteries included | Adds external runtime deps (violates FR-010); overkill (no client reactivity needed) | Rejected |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| Server-side singleton leaks labels across requests/tenants | High | Med | Use React Context as the source of truth (Decision 1); any singleton is hydrated client-only and treated as a non-authoritative cache |
+| Localization endpoint latency adds to TTFB | Med | Med | Single-flight cache per `(entryId, locale)`; fetch in parallel with other loader calls via `Promise.all`; in-memory process cache |
+| Endpoint failure blanks the page | High | Low | Service swallows errors and returns `{}`; `t()` fallback returns the key |
+| `ENTRY_ID` drift between features and content platform | Med | Med | Centralize IDs in one `as const` map; type the keys so misuse fails at compile time |
+
+### Key Decisions
+
+#### Decision 1: Dedicated React Context, placed OUTSIDE `BuyerPortalProvider`
+
+- **Status**: Accepted
+- **Context**: Data is fetched server-side and injected into the page. Components need global, prop-drill-free access. The app injects per-page context through `withProviders` → `BuyerPortalProvider`. **Critical finding**: `withBuyerPortal` destructures and **strips** `context` before rendering its child (`const { context, ...componentProps } = props`), so any provider placed *inside* `withBuyerPortal` never receives `context.localization`. Additionally, `LoadingTabsLayout` (which renders route titles) lives inside `BuyerPortalProvider`, so translating loading titles requires localization to wrap it.
+- **Decision**: Add a dedicated `LocalizationProvider` to the `withProviders` chain with order `[withAuth, withLocalization, withBuyerPortal]` (→ tree `withAuth › withLocalization › withBuyerPortal › Component`). `withLocalization` receives `context` from `withAuth`, reads `context.localization.labels`, renders `LocalizationProvider`, and **forwards the full props (including `context`)** down to `withBuyerPortal`. The `LocalizationProvider` thus wraps `BuyerPortalProvider` and its `LoadingTabsLayout`.
+- **Consequences**: SSR-safe (value lives per request/render, never on a shared module). `withLocalization` correctly receives the injected labels (fixes the strip-context bug). Loading titles become translatable. `t` is recreated only when `labels` change (effectively once per page).
+
+#### Decision 2: `t` is a pure factory `createLocalize(labels) => t`
+
+- **Status**: Accepted
+- **Context**: The fallback + interpolation logic must be unit-testable and independent of React.
+- **Decision**: Implement `createLocalize(labels: LabelMap)` returning `t(key, interpolations?)`. The hook memoizes the factory output; tests call the factory directly.
+- **Consequences**: Logic is decoupled from React; trivially testable; reusable from non-component code by passing the map.
+
+#### Decision 3: Optional client-only singleton (non-authoritative)
+
+- **Status**: Accepted (optional)
+- **Context**: Some non-React utilities may want `t()` without access to the provider.
+- **Decision**: The `LocalizationProvider` may hydrate a `labelStore` singleton **only on the client** (`typeof window !== "undefined"`) for convenience. Context remains authoritative; the singleton is never read during SSR.
+- **Consequences**: Enables ad-hoc `t()` outside React on the client, without risking cross-request contamination on the server.
+
+#### Decision 4: Transform array → map once, in the Service
+
+- **Status**: Accepted
+- **Context**: FR-004 requires O(1) lookups and no per-render iteration.
+- **Decision**: `getLocalizationLabelsService` reduces `labels[]` into `Record<string,string>` immediately after fetch, before returning to the loader.
+- **Consequences**: The component layer only ever sees the flat map; no `.find()` at render.
+
+#### Decision 5: Permanent process-local cache (no TTL)
+
+- **Status**: Accepted
+- **Context**: Labels are global and change rarely. The base `Client` uses `next: { revalidate: 300 }`, but a permanent service-level cache shadows it.
+- **Decision**: Keep a permanent `Map<string, LabelMap>` (`resolved`) plus a single-flight `Map<string, Promise<LabelMap>>` (`inFlight`), keyed by `(entryId, locale)`. No TTL.
+- **Consequences**: Fastest possible lookups, minimal network. Trade-off: edited translations only propagate after a process restart/deploy. Aligns with the documented "in-memory process-local cache only" constraint.
+
+#### Decision 6: No auth — labels are public/global
+
+- **Status**: Accepted
+- **Context**: The localization endpoint is a central VTEX content repo (account `vtex`), independent of the host store and user.
+- **Decision**: `LocalizationClient` does not forward the host-store cookie/credentials. Labels are treated as public/global content.
+- **Consequences**: A single cache entry per `(entryId, locale)` serves all users (no per-user cache, no risk of serving one user's content to another). No auth leakage to a cross-domain host.
+
+#### Decision 7: Multi-entry merge with automatic `shared`
+
+- **Status**: Accepted
+- **Context**: Pages typically need their domain labels plus common `shared.*` labels. Keys are already namespaced, so merging is collision-safe.
+- **Decision**: `getLocalizationLabelsService` accepts a params object `{ entryIds: entryId | entryId[], locale? }`, always adds the `shared` entry, fetches each (cached/de-duped), and merges the maps via `Object.assign`.
+- **Consequences**: Loaders pass only their domain entry; `shared` is guaranteed everywhere. Less boilerplate; deterministic merge.
+
+#### Decision 8: `t()` overloaded to accept `ReactNode[]` and return `ReactNode`
+
+- **Status**: Accepted
+- **Context**: Some translated strings contain embedded interactive elements (links, bold text, etc.).
+  The original `t()` returns a plain `string`, which forces callers to manually split the translated
+  string by a sentinel placeholder and interleave React nodes — a fragile and verbose IIFE pattern.
+- **Decision**: `LocalizeFn` is changed from a single function signature to an **overloaded call
+  signature** with two variants:
+  1. `(key, (string | number)[]) → string` — the original fast path, unchanged (uses `String.replace`).
+  2. `(key, ReactNode[]) → ReactNode` — new path; activated automatically by TypeScript when at least
+     one interpolation value is not a `string | number`. Internally uses a `RegExp.exec()` loop
+     (`interpolateNodes`) to build a `ReactNode[]` of alternating text segments and the caller-supplied
+     nodes, which React renders as normal JSX children.
+  TypeScript selects the correct overload at the call site: passing `[<a>...</a>]` resolves to the
+  second overload; passing `[1, 25]` resolves to the first.
+- **Consequences**:
+  - IIFEs and manual `split`/`interleave` are eliminated from components.
+  - The string-interpolation path is unaffected (no performance regression).
+  - Callers must add `key` props to JSX elements they pass as interpolations (standard React requirement for array children).
+  - `createLocalize` introduces a `react` type-only import; the runtime helpers (`hasReactNodes`,
+    `interpolateNodes`) add no external dependency.
+
+### Implementation Plan
+
+1. **Types & constants** — `src/features/shared/localization/types.ts`, `src/features/shared/localization/constants.ts` (`LOCALIZATION_ENTRY_IDS as const`, `LOCALIZATION_CONTENT_TYPE`, `LOCALIZATION_BASE_URL`).
+2. **Client** — `src/features/shared/localization/clients/LocalizationClient.ts` (extends `Client`, content-platform base URL).
+3. **Service** — `src/features/shared/localization/services/get-localization-labels.service.ts` (multi-entry merge + auto-`shared` + permanent cache + single-flight + error log + fallback).
+4. **Localize factory** — `src/features/shared/localization/createLocalize.ts` (pure `t`).
+5. **Context/Provider/Hook** — `LocalizationProvider`, `useLocalization`, insert `withLocalization` into the `withProviders` chain **before** `withBuyerPortal` (`[withAuth, withLocalization, withBuyerPortal]`).
+6. **Loader integration** — page loader calls the service and returns `localization` in `context`; `withLocalization` HOC reads `context.localization.labels` and forwards full props down to `withBuyerPortal`.
+7. **Tests** — unit tests for transform, `t` interpolation, fallback.
+8. **Verification** — `make check` (lint + typecheck + test).
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+#### API response types (`src/features/shared/localization/types.ts`)
+
+```typescript
+import type { ReactNode } from "react";
+
+export type LocalizationLanguageType = {
+  name: string;
+  language_code: string;
+  native_name: string;
+  script: string;
+  text_direction: "ltr" | "rtl" | string;
+  utf_encoding: string;
+};
+
+export type LocalizationRegionType = {
+  name: string;
+  flag: string;
+  country_code: string;
+  continent: string;
+  date_format: string;
+  time_format: "12h" | "24h" | string;
+  time_format_mask: string;
+  unit_system: "imperial" | "metric" | string;
+  default_timezone: string;
+};
+
+export type LocalizationLocaleMetadataType = {
+  code: string;
+  locale: string;
+  language: LocalizationLanguageType;
+  region: LocalizationRegionType;
+};
+
+export type LocalizationLabelType = {
+  key: string;
+  value: string;
+};
+
+export type LocalizationLocaleDataType = {
+  locale_metadata: LocalizationLocaleMetadataType; // typed, not consumed yet
+  labels: LocalizationLabelType[];
+};
+
+/** Flat, O(1)-lookup label map produced by the service. */
+export type LabelMap = Record<string, string>;
+
+/** Parameters accepted by `getLocalizationLabelsService`. */
+export type GetLocalizationLabelsParams = {
+  entryIds: LocalizationEntryId | LocalizationEntryId[];
+  locale?: string;
+};
+
+/**
+ * Localize function exposed to components.
+ *
+ * Two call signatures (Decision 8):
+ *  - `t(key, (string | number)[])` → `string`   – pure text interpolation (O(1) replace)
+ *  - `t(key, ReactNode[])`          → `ReactNode` – node interpolation; returns an array of
+ *    alternating text segments and the supplied React nodes, ready to spread inside JSX.
+ *
+ * TypeScript selects the correct overload automatically based on the interpolation array type.
+ */
+export type LocalizeFn = {
+  (key: string, interpolations?: (string | number)[]): string;
+  (key: string, interpolations: ReactNode[]): ReactNode;
+};
+```
+
+#### Feature entry IDs (`src/features/shared/localization/constants.ts`)
+
+```typescript
+export const LOCALIZATION_ENTRY_IDS = {
+  shared: "shared-entry-id-example",
+  orgUnits: "org-units-entry-id-example",
+  users: "users-entry-id-example",
+} as const;
+
+export type LocalizationFeature = keyof typeof LOCALIZATION_ENTRY_IDS;
+export type LocalizationEntryId = (typeof LOCALIZATION_ENTRY_IDS)[LocalizationFeature];
+
+/** Content type slug in the Content Platform API path (see cms_content_type__i18n.jsonc). */
+export const LOCALIZATION_CONTENT_TYPE = "i18n";
+
+export const LOCALIZATION_BASE_URL = `https://vtex.vtexcommercestable.com.br/api/content-platform/data/vtex/b2b/${LOCALIZATION_CONTENT_TYPE}`;
+```
+
+### Interfaces
+
+#### Client — `LocalizationClient`
+
+```typescript
+import { Client } from "../../clients/Client";
+import { LOCALIZATION_BASE_URL } from "../constants";
+
+import type { LocalizationLocaleDataType } from "../types";
+
+export class LocalizationClient extends Client {
+  constructor() {
+    super(LOCALIZATION_BASE_URL);
+  }
+
+  // No `Cookie` header is passed: labels are public/global content (Decision 6),
+  // so the base Client adds no auth header for this request.
+  getEntry(entryId: string, locale: string = "") {
+    return this.get<LocalizationLocaleDataType>(`/entries/${entryId}`, {
+      params: { locale },
+      componentName: "LocalizationClient",
+    });
+  }
+}
+
+export const localizationClient = new LocalizationClient();
+```
+
+#### Service — `getLocalizationLabelsService` (multi-entry merge + auto-`shared` + permanent cache + single-flight + error log + fallback)
+
+```typescript
+import { logError } from "../../services/logger";
+import { localizationClient } from "../clients/LocalizationClient";
+import {
+  LOCALIZATION_ENTRY_IDS,
+  type LocalizationEntryId,
+} from "../constants";
+
+import type { LocalizationLabelType, LabelMap, GetLocalizationLabelsParams } from "../types";
+
+// Permanent process-local cache + single-flight, keyed by (entryId, locale).
+const resolved = new Map<string, LabelMap>();
+const inFlight = new Map<string, Promise<LabelMap>>();
+
+const toLabelMap = (labels: LocalizationLabelType[]): LabelMap =>
+  labels.reduce<LabelMap>((acc, { key, value }) => {
+    acc[key] = value;
+    return acc;
+  }, {});
+
+// Fetches (and caches) a single entry; logs error and falls back to {} on failure.
+const fetchEntry = (entryId: string, locale: string): Promise<LabelMap> => {
+  const cacheKey = `${entryId}::${locale}`;
+
+  const cached = resolved.get(cacheKey);
+  if (cached) return Promise.resolve(cached);
+
+  const ongoing = inFlight.get(cacheKey);
+  if (ongoing) return ongoing;
+
+  const promise = localizationClient
+    .getEntry(entryId, locale)
+    .then((data) => {
+      const map = toLabelMap(data?.labels ?? []);
+      resolved.set(cacheKey, map); // permanent cache (no TTL)
+      return map;
+    })
+    .catch((error: unknown) => {
+      logError("Failed to fetch localization labels", {
+        entryId,
+        locale,
+        error_message: error instanceof Error ? error.message : String(error),
+      });
+      return {} as LabelMap; // graceful fallback: t() returns keys
+    })
+    .finally(() => {
+      inFlight.delete(cacheKey);
+    });
+
+  inFlight.set(cacheKey, promise);
+  return promise;
+};
+
+export const getLocalizationLabelsService = async ({
+  entryIds,
+  locale = "",
+}: GetLocalizationLabelsParams): Promise<LabelMap> => {
+  const requested = Array.isArray(entryIds) ? entryIds : [entryIds];
+
+  // Always include `shared`; de-duplicate.
+  const ids = Array.from(new Set<LocalizationEntryId>([LOCALIZATION_ENTRY_IDS.shared, ...requested]));
+
+  const maps = await Promise.all(ids.map((id) => fetchEntry(id, locale)));
+
+  // Namespaced keys make this merge collision-safe.
+  return Object.assign({}, ...maps) as LabelMap;
+};
+```
+
+> `logError(message, metadata?)` is the existing OTLP logger convenience function exported
+> from `src/features/shared/services/logger`.
+
+#### Localize factory — `createLocalize` (pure)
+
+Two execution paths dispatched at runtime by `hasReactNodes` (see Decision 8):
+
+```typescript
+import type { ReactNode } from "react";
+import type { LabelMap, LocalizeFn } from "./types";
+
+const PLACEHOLDER_PATTERN = /\{(\d+)\}/g;
+
+// Returns true when the array contains at least one value that is not string or number.
+const hasReactNodes = (interpolations: (string | number | ReactNode)[]): boolean =>
+  interpolations.some(
+    (v) => v !== null && v !== undefined && typeof v !== "string" && typeof v !== "number"
+  );
+
+// Builds [textSegment, node, textSegment, ...] using exec() so ReactNode values
+// are inserted at placeholder positions without stringification.
+const interpolateNodes = (template: string, interpolations: ReactNode[]): ReactNode[] => {
+  const result: ReactNode[] = [];
+  const regex = new RegExp(PLACEHOLDER_PATTERN.source, "g");
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(template)) !== null) {
+    if (match.index > lastIndex) result.push(template.slice(lastIndex, match.index));
+    const idx = Number(match[1]);
+    const value = interpolations[idx];
+    result.push(value !== undefined ? value : match[0]);
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex < template.length) result.push(template.slice(lastIndex));
+
+  return result;
+};
+
+export const createLocalize = (labels: LabelMap): LocalizeFn => {
+  function t(key: string, interpolations?: (string | number)[]): string;
+  function t(key: string, interpolations: ReactNode[]): ReactNode;
+  function t(key: string, interpolations?: (string | number | ReactNode)[]): string | ReactNode {
+    const template = labels[key];
+
+    if (template === undefined) return key;            // fallback: key itself
+    if (!interpolations || interpolations.length === 0) return template;
+
+    if (hasReactNodes(interpolations)) {
+      return interpolateNodes(template, interpolations as ReactNode[]);
+    }
+
+    // Pure string/number path — O(1) replace.
+    return template.replace(PLACEHOLDER_PATTERN, (token, index: string) => {
+      const value = (interpolations as (string | number)[])[Number(index)];
+      return value === undefined ? token : String(value);
+    });
+  }
+
+  return t as LocalizeFn;
+};
+```
+
+#### Context, Provider & Hook
+
+```typescript
+// src/features/shared/localization/LocalizationContext.tsx
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+import { createLocalize } from "./createLocalize";
+
+import type { LabelMap, LocalizeFn } from "./types";
+
+type LocalizationContextType = { t: LocalizeFn; labels: LabelMap };
+
+const LocalizationContext = createContext<LocalizationContextType | undefined>(undefined);
+
+export const LocalizationProvider = ({
+  labels,
+  children,
+}: {
+  labels: LabelMap;
+  children: ReactNode;
+}) => {
+  const value = useMemo<LocalizationContextType>(
+    () => ({ labels, t: createLocalize(labels) }),
+    [labels]
+  );
+  return <LocalizationContext.Provider value={value}>{children}</LocalizationContext.Provider>;
+};
+
+export const useLocalization = (): LocalizationContextType => {
+  const ctx = useContext(LocalizationContext);
+  // Defensive fallback so t() never crashes outside a provider.
+  return ctx ?? { labels: {}, t: createLocalize({}) };
+};
+```
+
+#### HOC — `withLocalization` (mirrors `withBuyerPortal`)
+
+```typescript
+// src/features/shared/localization/withLocalization.tsx
+import { type ComponentType } from "react";
+
+import { LocalizationProvider } from "./LocalizationContext";
+
+import type { LabelMap } from "./types";
+
+export const withLocalization = <T extends Record<string, unknown>>(
+  Component: ComponentType<T>
+) =>
+  function WrappedWithLocalization(
+    props: T & { context: { localization?: { labels: LabelMap } } }
+  ) {
+    const labels = props.context?.localization?.labels ?? {};
+    return (
+      <LocalizationProvider labels={labels}>
+        {/* Forward ALL props (including `context`) so `withBuyerPortal` downstream
+            still receives it. `withLocalization` must sit BEFORE `withBuyerPortal`, which
+            strips `context` (see Decision 1 in specs/custom-localization-system.md). */}
+        <Component {...props} />
+      </LocalizationProvider>
+    );
+  };
+```
+
+`withLocalization` is inserted into the shared `projectProviders` chain **before** `withBuyerPortal`:
+
+```typescript
+// src/features/shared/utils/withProviders.tsx (modified)
+// reduceRight applies right→left, so the tree is:
+//   withAuth › withLocalization › withBuyerPortal › Component
+// withLocalization thus wraps BuyerPortalProvider (and its LoadingTabsLayout) and still
+// receives `context` (withBuyerPortal would otherwise strip it).
+const projectProviders: ProviderHOC[] = [withAuth, withLocalization, withBuyerPortal];
+```
+
+### Integration Points
+
+#### Loader injection (server-side) — example in a page under `src/pages/`
+
+```typescript
+// src/pages/org-units.tsx (excerpt)
+import { getLocalizationLabelsService } from "../features/shared/localization/services/get-localization-labels.service";
+import { LOCALIZATION_ENTRY_IDS } from "../features/shared/localization/constants";
+// ...existing imports (withAuthLoader, withProviders, etc.)
+
+export async function loaderFunction(data: LoaderData<OrgUnitsQuery>) {
+  return withAuthLoader(data, async ({ cookie, ...clientContext }) => {
+    const [orgUnits, localizationLabels] = await Promise.all([
+      getOrgUnitsService({ cookie /* ... */ }),
+      // `shared` is merged automatically; pass an array for multiple domains.
+      // locale comes from the browser/request context; empty string as fallback.
+      getLocalizationLabelsService({ entryIds: LOCALIZATION_ENTRY_IDS.orgUnits, locale: data.locale }),
+    ]);
+
+    return {
+      data: orgUnits,
+      context: {
+        clientContext: { cookie, ...clientContext },
+        localization: { labels: localizationLabels }, // <- consumed by withLocalization
+      },
+    };
+  });
+}
+
+export default withProviders(OrgUnitsPage); // withProviders now includes withLocalization
+```
+
+#### Component consumption (client) — examples in child components
+
+**String interpolation** — `t()` returns `string`:
+
+```typescript
+// Any component under the provider tree
+import { useLocalization } from "../../shared/localization/LocalizationContext";
+
+export const PaginationLabel = ({ from, to, total }: { from: number; to: number; total: number }) => {
+  const { t } = useLocalization();
+
+  // Label JSON: { "shared.pagination.label": "De {0} a {1} itens de {2}" }
+  return <span>{t("shared.pagination.label", [from, to, total])}</span>;
+  // -> "De 1 a 25 itens de 100"
+};
+```
+
+**ReactNode interpolation** — `t()` returns `ReactNode` (Decision 8):
+
+```tsx
+// Label JSON: { "users.delete.messages.confirmDeleteUser": "Permanently delete {0}?" }
+export const DeleteConfirmation = ({ user }: { user: { id: string; name: string } }) => {
+  const { t } = useLocalization();
+
+  return (
+    <p>
+      {t("users.delete.messages.confirmDeleteUser", [
+        <a key="user-name" href={`/user/${user.id}`}>{user.name}</a>,
+      ])}
+    </p>
+    // -> <p>Permanently delete <a href="/user/42">Jane Doe</a>?</p>
+  );
+};
+```
+
+TypeScript selects the `ReactNode` overload automatically because `<a>` is not a `string | number`.
+The caller is responsible for adding `key` props to JSX elements passed as interpolations.
+
+#### Error-path label loading (`withLoaderErrorBoundary` and `withAuthLoader`)
+
+When a page loader throws (caught by `withLoaderErrorBoundary`) or authentication fails (caught by `withAuthLoader`), the system still needs localization labels so the error UI can display translated strings via `t()`.
+
+Both utilities follow the same pattern:
+
+1. Call `getLocalizationLabelsService({ entryIds: LOCALIZATION_ENTRY_IDS.shared, locale: data.locale ?? "" })` — fetches only the `shared` entry (common labels are sufficient for error states) and never throws (graceful fallback to `{}`).
+2. Embed the result as `context.localization.labels` in the error response shape.
+3. `withAuth` (the HOC) detects the unauthorized/error state (`!props.authorized`) and forwards `props.context` as `errorContext` to the wrapped component, so `withLocalization` can read `context.localization.labels` and provide a valid `t()` even in the error render path.
+
+This guarantees that the Error Boundary page renders with translated labels (or at minimum key-as-fallback behavior) regardless of whether the original loader succeeded.
+
+### Invariants & Constraints
+
+- **Server-only fetch**: `getLocalizationLabelsService` is invoked exclusively from page loaders. Components never trigger localization network requests.
+- **Single transform**: `labels[]` → `LabelMap` happens once per `(entryId, locale)`; render-time lookups are O(1).
+- **`shared` always present**: every resolved map includes the `shared` entry, merged with any requested domain entries (namespaced keys → collision-safe).
+- **Global, unauthenticated labels**: no host-store cookie is forwarded; one cache entry per `(entryId, locale)` serves all users.
+- **Permanent cache**: the `resolved` map has no TTL; updated translations propagate on process restart/deploy.
+- **Never throws**: a failed fetch logs an error and yields an empty `LabelMap`; `t()` returns the key.
+- **Idempotent fallback**: `t(key)` with a missing key always returns exactly `key`; unmatched `{n}` tokens are left intact in both the string and node paths.
+- **ReactNode interpolation is additive**: passing a `ReactNode[]` activates `interpolateNodes` and returns a `ReactNode[]`; callers must provide `key` props on JSX elements in the array (standard React requirement). The string-interpolation path is unaffected.
+- **Provider placement**: `LocalizationProvider` sits outside `BuyerPortalProvider` (`withLocalization` before `withBuyerPortal`) so it receives `context` and wraps `LoadingTabsLayout`.
+- **No cross-request state on the server**: React Context is authoritative.
+- **Plugin boundary**: all localization code lives in `src/features/shared/localization/`; no new route registration in `plugin.config.js` is required.
+- **Zero new runtime dependencies** (FR-010); strict TypeScript with no unjustified `any`.
+
+### Files to Create / Change
+
+| File | Change |
+|---|---|
+| `src/features/shared/localization/types.ts` | API response types, `LabelMap`, `LocalizeFn` |
+| `src/features/shared/localization/constants.ts` | `LOCALIZATION_ENTRY_IDS as const`, `LOCALIZATION_CONTENT_TYPE`, `LOCALIZATION_BASE_URL` |
+| `src/features/shared/localization/clients/LocalizationClient.ts` | HTTP client (extends `Client`) |
+| `src/features/shared/localization/services/get-localization-labels.service.ts` | Multi-entry merge + auto-`shared` + permanent cache + single-flight + error log + fallback |
+| `src/features/shared/localization/createLocalize.ts` | Pure `t` factory |
+| `src/features/shared/localization/LocalizationContext.tsx` | Context, `LocalizationProvider`, `useLocalization` |
+| `src/features/shared/localization/withLocalization.tsx` | HOC reading `context.localization.labels`, forwards full props |
+| `src/features/shared/utils/withProviders.tsx` | Insert `withLocalization` **before** `withBuyerPortal` in `projectProviders` |
+| `src/pages/<page>.tsx` | Loader fetches labels and returns `context.localization` |
+| `src/features/shared/localization/__tests__/*` | Unit tests (transform, interpolation, fallback) |