@salesforce/afv-skills 1.33.0 → 1.35.0

package/skills/experience-ui-bundle-localize/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: experience-ui-bundle-localize
+description: "MUST activate to localize / internationalize a uiBundles/*/src/ React project: extract hardcoded user-facing strings into Custom Labels, wire i18next over the Platform SDK GraphQL backend, add a language to a localized bundle, or troubleshoot label rendering across locales. Triggers: user-facing string literals in .tsx/.jsx, a CustomLabels.labels-meta.xml, a src/i18n/ directory or label-manifest.ts, t(…) calls, or requests to 'translate / localize / internationalize / support another language.' Scope: authenticated UI Bundles only (B2E CustomApplication-bound, or in-core accessCheck-bound apps). DO NOT TRIGGER when: the bundle is a site (B2C/B2B) app bound to a DigitalExperienceConfig (site localization not yet supported), building app shell/UI or styling, reading/writing/refreshing records (use experience-ui-bundle-salesforce-data-access), generating a new bundle (use experience-ui-bundle-frontend-generate), deploying (use experience-ui-bundle-deploy), or authoring translations in Translation Workbench."
+metadata:
+  version: "1.0"
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "experience-ui-bundle-deploy"
+    - "experience-ui-bundle-frontend-generate"
+    - "experience-ui-bundle-salesforce-data-access"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["npm"]
+      semver: ">=7.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Localize a React UI Bundle
+
+Walk a developer through localizing a React UI Bundle: detect hardcoded user-facing strings, extract them into Salesforce Custom Labels, wire up i18next over the Platform SDK GraphQL backend, and verify labels render across locales.
+
+This file is the **workflow + guardrail spine**. Depth lives in linked docs:
+
+- **[references/i18n-setup.md](references/i18n-setup.md)**: the two files you write: the i18next init and the label manifest
+- **[references/label-xml.md](references/label-xml.md)**: Custom Labels and translation metadata XML shapes; the `namespace:Key` rules
+- **[references/interpolation.md](references/interpolation.md)**: positional `{0}/{1}` placeholder interpolation in labels
+- **[references/verifying.md](references/verifying.md)**: serve URL, locale flip, and verifying labels render
+- **[references/gotchas.md](references/gotchas.md)**: the three silent-fail traps: unregistered manifest keys, API-version bake-in, stale label cache
+
+## The one-paragraph mental model
+
+A React UI Bundle can't use `@salesforce/label/*` the way LWC does, those imports resolve at compile time inside the platform's compiler, which your standalone React bundle doesn't go through. Instead, your app **fetches labels at runtime** through the Salesforce GraphQL UI API and hands them to **i18next** (a standard React i18n library) to render. The Platform SDK provides the runtime plumbing for this, a detector that reads the user's language, a backend that fetches labels over GraphQL, and a context fetch. You write two thin files: a short init that wires the SDK pieces into i18next, and a manifest listing which labels your app uses. The rest is authoring the labels themselves as Salesforce Custom Labels metadata.
+
+```typescript
+import { useTranslation } from "react-i18next";
+
+function WelcomeBanner() {
+  const { t } = useTranslation("c"); // "c" = custom label namespace
+  return <h1>{t("Welcome_Text")}</h1>; // renders "Welcome" or "Bienvenido" per user's language
+}
+```
+
+---
+
+## Step 0: Route the task
+
+| The task is… | Go to |
+|---|---|
+| Bundle doesn't exist yet | **experience-ui-bundle-frontend-generate** skill |
+| Deploying the app with its labels | **experience-ui-bundle-deploy** skill |
+| Localizing an existing bundle | **Workflow below** |
+
+---
+
+## Preconditions: verify before editing
+
+| # | Requirement | Verify | If missing |
+|---|---|---|---|
+| 1 | It's a `uiBundles/*/src/` React project | Project structure matches | Not a UI Bundle → route to the correct skill |
+| 2 | `@salesforce/platform-sdk` installed (≥11.42.1) | `package.json` in the UI bundle dir | Tell user to install it; cannot proceed |
+| 3 | You can identify where the app mounts | Read the entry file (usually `src/index.tsx`) | No clear mount point → ask user to point it out |
+| 4 | Target org actually supports API v68.0+ (runtime label GraphQL for UI Bundles ships in Release 264) | Run the runtime org-release check below | Org's max API version is below v68.0 (Release 262 or older) → cannot proceed; retarget a Release 264+ org or upgrade the org |
+| 5 | The bundle is an authenticated app (B2E, or an in-core internal app), not a public site | Run the authenticated-app detection below | Bundle is a site (B2C/B2B) app → localization is **not yet supported for site bundles**; stop and tell the user B2C support is planned for when B2C localization is ready |
+
+**Runtime org-release check (precondition 4).** The `platform.labels` GraphQL path that resolves labels at runtime for UI Bundles ships in Salesforce Release 264 (API v68.0 or higher). A `sourceApiVersion` in `sfdx-project.json` records what you declared, not what the org supports, so a newer CLI pointed at an older org can pass a static file check and then fail at runtime. Query the org's actual maximum API version before wiring anything:
+
+```bash
+bash <skill-dir>/scripts/check-org-api-version.sh <org-alias-or-username>
+```
+
+Exit `0` → the org supports v68.0+, proceed. Exit `1` → the org is too old or unreachable; do not write i18n wiring or labels, report the version mismatch to the user and stop. (`sf api request rest` inside the script keeps authentication at the CLI transport layer, so no access token enters context.)
+
+**Authenticated-app detection (precondition 5).** The bundle's type decides whether localization is supported, and it's decided by deterministic file and string checks. Pass the full path to the bundle dir; the script derives the metadata root from it, so the current directory does not matter:
+
+```bash
+bash <skill-dir>/scripts/detect-bundle-type.sh <path-to-uiBundles/<name>/ dir>
+```
+
+Act on the exit code: `0` → authenticated app (in-core internal or B2E), proceed; `1` → site (B2C/B2B), localization is **not yet supported for site bundles**, stop and tell the user (B2C support is planned for when B2C localization is ready); `2` → unbound or cannot auto-detect, **ask the user to confirm** the bundle is an authenticated app (B2E or in-core internal) and stop if they cannot.
+
+If a precondition isn't met, stop: report the specific block to the user and record a plan item to return once it's resolved. Do not edit the bundle, in particular, never add i18n wiring or TODO markers to a site (B2C/B2B) bundle that precondition 5 gated off as unsupported.
+
+---
+
+## Workflow: the five steps
+
+Each step has a **checkable completion criterion** and a **confirm-before-continue** pause.
+
+### Step 1: Detect
+
+**Goal:** Scan `.tsx`/`.jsx` files for user-facing hardcoded strings.
+
+**What to scan:**
+- String literals inside JSX tags: `<h1>Welcome</h1>` → candidate
+- String props shown to users: `placeholder="Enter name"` → candidate
+- User-facing accessible text: `aria-label`, `aria-describedby`, `alt` → candidate (a screen-reader user hears these, so they must localize too)
+
+**What to skip:**
+- Import statements
+- Object keys / property names
+- `data-*` attributes (machine-readable)
+- Test IDs (`data-testid`, `id` attributes)
+- Text already wrapped in `t()` calls
+- Console logs, error messages thrown to developers (not user-facing)
+- Class names, file paths, technical constants
+
+**Action:**
+1. Scan the `src/` directory for `.tsx` and `.jsx` files
+2. Extract candidates, showing file path + line number for each
+3. Show the list to the developer
+
+**Completion criterion:**
+Developer confirms the list (or edits it to remove false positives).
+
+**Pause:** "I found N user-facing strings across M components. Here's the list: [show file:line + string]. Look right? [confirm / edit the list / skip some]"
+
+---
+
+### Step 2: Extract
+
+**Goal:** For each confirmed string, add a Custom Label and replace the JSX literal with a `t()` call.
+
+**Action for each string:**
+1. **Propose a key name**, format: `<Context>_<Role>` (e.g., `"Welcome"` → `Welcome_Text`, `"Save"` → `Save_Button`, `"Failed to save"` → `Save_Failed_Message`). Follow naming: PascalCase words, underscores between parts, descriptive enough to be unique.
+2. **Add the label** to `force-app/main/default/labels/CustomLabels.labels-meta.xml`:
+   ```xml
+   <labels>
+     <fullName>Welcome_Text</fullName>
+     <language>en_US</language>
+     <protected>false</protected>
+     <shortDescription>Welcome banner heading</shortDescription>
+     <value>Welcome</value>
+   </labels>
+   ```
+   (Full XML structure: [references/label-xml.md](references/label-xml.md))
+3. **Replace the string** in the component with `{t("Key")}`:
+   ```tsx
+   // Before: <h1>Welcome</h1>
+   // After:  <h1>{t("Welcome_Text")}</h1>
+   ```
+4. **Add the import** if not present: `import { useTranslation } from "react-i18next";` and `const { t } = useTranslation("c");` at the top of the component function.
+
+**Completion criterion:**
+Every confirmed string has both a `CustomLabels` entry and a `t()` call in its original location.
+
+**Pause:** "For each string I'll add a Custom Label and replace the JSX with t(). Here are the proposed keys: [show string → namespace:Key mapping]. Apply these edits? [y / review each]"
+
+---
+
+### Step 3: Register
+
+**Goal:** Add each key to the label manifest so i18next knows to fetch it.
+
+**Action:**
+1. Add each key to the manifest array in `src/i18n/label-manifest.ts`:
+   ```typescript
+   export const labelManifest = [
+     "c:Welcome_Text",
+     "c:Save_Button",
+     "c:Save_Failed_Message",
+   ];
+   ```
+   If the file doesn't exist yet, Step 4 scaffolds it; the completion check below reports its absence, so don't test for the file by hand.
+
+**Completion criterion:**
+Run `check-manifest-registered.sh` from the UI bundle dir (it scans `src/` relative to the current directory) and report any errors it returns. It owns the deterministic inspection: it cross-checks every `t("Key")` call site against the manifest and treats a missing `label-manifest.ts` (when `t()` calls exist) as a failure. A key that's called but not registered renders as its own literal name at runtime with no error, the silent-fail trap this guards.
+
+```bash
+cd <path-to-uiBundles/<name>/ dir>   # scripts scan src/ relative to here
+bash <skill-dir>/scripts/check-manifest-registered.sh
+```
+
+Branch on the exit code: `0`, every key is registered (or there are no `t()` calls to gate), proceed. `1`, the manifest is missing or the listed keys aren't in it; scaffold or add them (Step 4 scaffolds the file) and re-run. `64`, usage error, the source dir doesn't exist (wrong cwd or bad argument); this is **not** a "keys missing" result, do not scaffold or register, fix the path and re-run.
+
+**Pause:** "Added N entries to label-manifest.ts. check-manifest-registered.sh passed: [confirm]."
+
+---
+
+### Step 4: Wire
+
+**Goal:** Ensure the i18next init exists; scaffold it if the app has no i18n yet.
+
+**Check:**
+Run `check-i18n-wired.sh` from the UI bundle dir (it scans `src/` relative to the current directory) and report what it returns. The script owns the whole deterministic inspection: it looks for an init file defining `initI18n()` and a boot-time call to it, and when those exist it also reports whether the label manifest is imported and actually passed into the backend config. Do not re-derive any of this by reading files yourself.
+
+```bash
+cd <path-to-uiBundles/<name>/ dir>   # scripts scan src/ relative to here
+bash <skill-dir>/scripts/check-i18n-wired.sh
+```
+
+Branch on the **exit code** (the printed message names the specific file/symbol for your report, but the decision is the code):
+- Exit `0` → fully wired, the manifest is passed into the backend; go to "If i18n already exists" below and just add new keys.
+- Exit `1` → no `initI18n()` exists; scaffold the whole setup via "If no i18n setup exists yet".
+- Exit `2` → the init already exists but isn't called at boot; do **not** re-scaffold or overwrite it. Add only the boot-time `initI18n()` call in the entry file (step 4 of "If no i18n setup exists yet"), then re-run.
+- Exit `3` → wired at boot but the script **could not confirm** the manifest is passed into the backend. It scans the whole `src` tree, but this last check is a textual heuristic: the manifest may be wired through a variable, spread, or helper the script can't see, so treat exit 3 as "verify before editing," not "definitely broken." Open the file the message names and confirm the manifest really isn't in `backendOptions`. Only if it genuinely dangles, do what the message names: if the manifest is imported but unused, pass it into the existing `backendOptions` without clobbering it; if there's no `backendOptions`/`SalesforceBackend` config at all, add that backend block to the existing init (see [references/i18n-setup.md](references/i18n-setup.md)). Never re-scaffold the init file or duplicate wiring that already works.
+- Exit `64` → usage error: the source dir doesn't exist (wrong cwd or bad argument). This is **not** a "no init" result; do not scaffold. Fix the path (run from the UI bundle dir, or pass its `src` path) and re-run.
+
+**If no i18n setup exists yet:**
+1. Install dependencies (tell the user to run):
+   ```bash
+   npm install i18next react-i18next i18next-chained-backend i18next-localstorage-backend
+   ```
+2. Create `src/i18n/index.ts` with the init wiring (full code: [references/i18n-setup.md](references/i18n-setup.md))
+3. Create `src/i18n/label-manifest.ts` with an empty array (Step 3 will populate it)
+4. Call `initI18n()` once at boot in the entry file (before mounting the app):
+   ```typescript
+   import { initI18n } from "./i18n";
+   
+   initI18n().then(() => {
+     // mount app
+   });
+   ```
+
+**If i18n already exists:**
+Act on the message `check-i18n-wired.sh` already printed (above): if it reports the manifest wired, just add new keys to it; if it reports a reconcile is needed, do exactly what its message names (import the manifest and/or pass it into the backend config) without clobbering existing wiring.
+
+**Completion criterion:**
+`initI18n()` exists and is called once at boot; the manifest is wired into the backend.
+
+**Pause:** "i18next setup [exists / created]. initI18n() is called at boot: [confirm]."
+
+---
+
+### Step 5: Verify
+
+**Goal:** Guide the developer to verify labels render in a second language.
+
+**Action:**
+1. **Activate a second language** (if not already active), tell the user: "In your org, go to Setup → Translation Workbench → Translation Settings → add a language (e.g., Spanish)."
+2. **Author a translation**, scaffold an empty translation file for the language:
+   ```xml
+   <!-- force-app/main/default/translations/es.translation-meta.xml -->
+   <Translations xmlns="http://soap.sforce.com/2006/04/metadata">
+     <customLabels>
+       <label>Bienvenido</label>
+       <name>Welcome_Text</name>
+     </customLabels>
+   </Translations>
+   ```
+   (Full structure: [references/label-xml.md](references/label-xml.md))
+   
+   Tell the user to either:
+   - Edit the XML file by hand (for a small number of labels), or
+   - Use Translation Workbench (Setup → Translate → Custom Label → pick language → enter translations), then retrieve with `sf project retrieve start --metadata Translations:es`.
+
+3. **Build and deploy**, tell the user:
+   ```bash
+   sf config set target-org=<alias>  # API version bakes in; point at the deploy target first
+   npm run build
+   sf project deploy start --source-dir force-app --target-org <alias>
+   ```
+
+4. **Open the app** at the `/lwr/application/ai/<namespace>-<bundleName>` URL on the `lightning.force.com` domain (redirects to the app host).
+
+5. **Change the user's Language** (not Locale), Setup → My Settings → Language & Time Zone → Language → pick the translated language → Save.
+
+6. **Reload the app**, labels should flip to the translated language.
+
+**If it doesn't render:**
+Check the three gotchas in [references/gotchas.md](references/gotchas.md):
+- Unregistered manifest key (Step 3 missed a label)
+- API-version mismatch (built against a different org)
+- Stale localStorage cache (clear `i18next_res_*` keys in DevTools)
+
+**Completion criterion:**
+Labels render in ≥2 locales, or the blocking gotcha is identified.
+
+**Pause:** "To verify: activate a second language in Translation Workbench, author a translation (I can scaffold the XML), build/deploy, and reload. Want me to scaffold the translation file for [language]? [y / I'll do it manually]"
+
+---
+
+## Edge cases: handle gracefully
+
+- **Already-localized code**: detect existing `t()` usage / a populated manifest; offer to *add to* the setup rather than re-scaffold everything.
+- **No strings found**: report cleanly and stop; do not invent work.
+- **App has no i18n setup yet**: Step 4 scaffolds the two files first before Step 3 can register anything.
+- **Partial setup** (manifest exists but init missing, or vice-versa), reconcile what's present; never clobber existing wiring.
+
+---
+
+## Guardrails: never regress these
+
+1. **Never machine-translate into deployable metadata.** Scaffold empty translation files and guide the developer to author translations (by hand or via Translation Workbench). Do not call any MT API and paste the result into `translation-meta.xml`; unreviewed machine translations are a quality liability.
+2. **Never register a key that has no label.** Manifest entry count must equal label count (Step 3 criterion). An unregistered key renders as its own literal name with no console warning. It's the most common localization bug.
+3. **Never clobber existing i18n wiring.** If Step 4 finds an existing `initI18n()`, reconcile (add the manifest import if missing) rather than replace the whole file.
+4. **Every file must be customer-safe.** No `webapps`, core-only paths, or internal infrastructure references anywhere. Write as if for an external customer in an SFDX project.
+
+---
+
+## Commands & layout
+
+```text
+<project-root>/                          ← SFDX project root
+└── force-app/main/default/
+    ├── labels/CustomLabels.labels-meta.xml          ← English base labels
+    ├── translations/<locale>.translation-meta.xml   ← one per translated language
+    └── uiBundles/<your-bundle>/
+        ├── package.json
+        └── src/
+            ├── i18n/
+            │   ├── index.ts              ← init wiring (you write this once)
+            │   └── label-manifest.ts     ← list of labels to fetch (you maintain this)
+            └── components/               ← components call t()
+```
+
+| Command | Run from | Purpose |
+|---|---|---|
+| `npm install i18next react-i18next i18next-chained-backend i18next-localstorage-backend` | UI bundle dir | Install i18n dependencies (Step 4) |
+| `npm run build` | UI bundle dir | Build the app (API version bakes in, set target-org first) |
+| `sf project deploy start --source-dir force-app` | Project root | Deploy the app + labels + translations |
+| `sf project retrieve start --metadata Translations:<locale>` | Project root | Pull translations authored in Translation Workbench |
+
+---
+
+## Pre-flight checklist: completion criteria for the whole run
+
+- [ ] Every confirmed string has both a `CustomLabels` entry and a `t()` call
+- [ ] `label-manifest.ts` entry count == label count (no unregistered keys)
+- [ ] `initI18n()` present and called once at boot
+- [ ] Labels render in ≥2 locales (or the blocking gotcha is named)
+- [ ] No hand-written machine translations landed in `*-meta.xml` (only scaffold-and-guide)

package/skills/experience-ui-bundle-localize/references/gotchas.md

@@ -0,0 +1,249 @@
+# Gotchas: the three silent-fail traps
+
+These are localization-specific problems that fail **silently** (no console warning, no error, just wrong text). If your app loads but labels are wrong, start here.
+
+---
+
+## 1. Unregistered manifest key → renders as literal key name
+
+**Symptom:** You see the literal string `Welcome_Text` on screen instead of "Welcome."
+
+**Cause:** The key isn't in your `label-manifest.ts`. The app only fetches labels that are listed in the manifest, so an unregistered key is **never requested**, and i18next, finding nothing in its cache, renders the **literal key string** back to you as a fallback.
+
+**No console warning. No error.** It fails silently. This is the most common localization bug.
+
+**Example:**
+
+```typescript
+// src/i18n/label-manifest.ts
+export const labelManifest = [
+  "c:Save_Button",
+  // forgot "c:Welcome_Text"
+];
+```
+
+```typescript
+// component
+const { t } = useTranslation("c");
+return <h1>{t("Welcome_Text")}</h1>; // renders "Welcome_Text" (literal string)
+```
+
+**Fix:** Add the missing key to `label-manifest.ts`:
+
+```typescript
+export const labelManifest = [
+  "c:Save_Button",
+  "c:Welcome_Text", // ← add this
+];
+```
+
+**Why it's silent:** i18next is a general-purpose library. It doesn't know your labels come from Salesforce. When a key isn't in its cache, the fallback behavior (per i18next's design) is to render the key string, because in some apps, that's a valid debugging signal. In our case, it's just a trap.
+
+**Prevention:** Always keep manifest entry count equal to label count (Step 3 completion criterion in the workflow). PR review catches mismatches today.
+
+**Deeper detail:** The manifest is read by `SalesforceBackend` at boot. It groups entries by namespace (all `c:*` together, all `LightningDatatable:*` together) and issues a GraphQL query per namespace:
+
+```graphql
+query LoadLabels {
+  uiapi {
+    platform {
+      labels(namespace: "c", names: ["Save_Button", ...]) {
+        name
+        value
+        resolvedLocale
+      }
+    }
+  }
+}
+```
+
+If `Welcome_Text` isn't in the manifest, it isn't in the `names` array, so the server never returns it. i18next's cache is empty for that key, and the `t()` call falls back to rendering the key name.
+
+Within a namespace, `SalesforceBackend` also splits the names into batches of at most **100** and fires the queries in parallel, because `uiapi.platform.labels` rejects a call with more than 100 names. This is automatic: a manifest with hundreds of `c:*` keys works with no extra config on your part. See the "Large manifest" note under Related problems.
+
+---
+
+## 2. API-version bake-in → blank page after deploy
+
+**Symptom:** The app worked locally (or on a different org), but after deploying to a new org it boots to a **blank page** (white screen, no obvious error in the console).
+
+**Cause:** You built the app while pointed at a **different org** than the one you deployed to, and the API versions don't match. The build plugin reads your default org's API version and stamps it into the bundle's JavaScript:
+
+```javascript
+// baked into the built JS
+const endpoint = `https://<org>/services/data/v65.0/graphql`;
+```
+
+If you built while pointed at a v65.0 org and deploy to a v63.0 org, the bundle tries to call `/services/data/v65.0/graphql`, an endpoint that org doesn't have. The GraphQL call **404s**, the i18n context fetch (`fetchI18nContext()`) throws, and the app crashes during boot before React even mounts. You see a blank page.
+
+**Fix:** Before building, set the deploy target org as default so the versions match:
+
+```bash
+sf config set target-org=<your-deploy-target-alias>
+npm run build
+sf project deploy start --source-dir force-app --target-org <same-alias>
+```
+
+**Check an org's API version:**
+
+```bash
+sf org display --target-org <alias>
+```
+
+Look for `"API Version"` in the output (e.g., `63.0`).
+
+**Prevention:** Always run `sf config set target-org=<deploy-target>` **before** `npm run build`. The workflow (Step 1 of verifying) calls this out, but it's easy to forget when iterating.
+
+**Why it's silent:** The 404 happens in the SDK's GraphQL fetch, which throws a generic network error. The stack trace points at `fetchI18nContext`, but doesn't say "wrong API version"; you have to infer it from the 404. A mismatch of one minor version (e.g., v63 → v64) usually works (backward-compatible); a mismatch of two or more (v63 → v65) reliably breaks.
+
+**Not the same as the version floor:** The bake-in above is a *mismatch* problem (two orgs, different versions). Separate from it is a hard floor: runtime label resolution over GraphQL for UI Bundles works from **API v68.0 (the 264 release)** onward. The `platform.labels` field appears in the schema at v67.0, but the end-to-end feature is functional for UI Bundles at 264.4 / v68.0; on an org below that, a localized bundle renders blank or shows raw key names. This is why precondition 4 queries the org's actual maximum API version (via `check-org-api-version.sh`) before starting, rather than trusting the `sourceApiVersion` declared in `sfdx-project.json`: that field records what you declared, not what the org supports, so an org that old can't run this pattern even when the file check passes. Confirm an org's ceiling with `sf org display --target-org <alias>` (the `API Version` row) or by opening `/services/data/` and checking the highest `vNN.0` listed.
+
+**Version floor is not the same as release timing:** The precondition blocks orgs older than v68.0, but it cannot distinguish patch releases within v68 (264.3 vs 264.4 both report v68.0). If this skill is deployed to orgs mid-rollout (on 264.3, before 264.4 is live), it can still produce non-functional localized bundles. That is a release-coordination concern handled by when the skill ships, not by this check.
+
+---
+
+## 3. Stale localStorage cache → old translations persist
+
+**Symptom:** You changed a translation (edited the `translation-meta.xml` or updated it in Translation Workbench), confirmed the new value is in the org, redeployed, but the app **still shows the old text** on reload.
+
+**Cause:** Your `src/i18n/index.ts` chains two backends:
+
+```typescript
+backend: {
+  backends: [LocalStorageBackend, SalesforceBackend],
+  backendOptions: [
+    { expirationTime: 86400000 }, // 24 hours
+    { dataSDK, labelManifest },
+  ],
+},
+```
+
+On load, i18next reads labels from **localStorage first** (the `LocalStorageBackend`), and only falls through to the GraphQL fetch (the `SalesforceBackend`) on a **cache miss**. Labels are cached per language+namespace under keys like:
+
+- `i18next_res_en-c` (English custom labels)
+- `i18next_res_es-c` (Spanish custom labels)
+- `i18next_res_fr-c` (French custom labels)
+
+Each has an `expirationTime` of **24 hours** (86400000 milliseconds). Until that entry expires, your app serves the cached copy and **never refetches**, so a fresh org value doesn't appear.
+
+**What you see in DevTools:**
+- **Network tab** shows the i18n **context/detect** query on every reload (this is how the SDK reads the user's language).
+- But it shows **no labels query**, because the labels are served from localStorage, not the network.
+- This makes it look like "the network is fine, so why is the text stale?" But the network is fine *for the context fetch*; the labels never hit the network at all.
+
+**Fix:** Clear the cached labels, then reload:
+
+1. **DevTools → Application → Local Storage** → find your org's origin (e.g., `https://<org>.my.salesforce.app`)
+2. Delete the `i18next_res_*` keys (or **Clear site data** to wipe everything)
+3. Reload the app
+
+The next load misses the cache, refetches the labels over GraphQL, and shows the current value.
+
+**This is expected behavior, not a bug.** The cache is what makes labels fast after first load (no GraphQL roundtrip on every boot). In production, a translation change takes up to `expirationTime` to roll out to all users; during development, you manually clear the cache to see edits immediately.
+
+**Prevention:** When testing translation changes, habitually clear localStorage before reloading. Or lower `expirationTime` in the init file during development (e.g., 60000 = 1 minute), but remember to raise it back for production.
+
+**Why the GraphQL calls you DO see aren't label refetches:** The context query runs on every boot to detect the user's current language. It's a separate, small query:
+
+```graphql
+query I18nContext {
+  uiapi {
+    platform {
+      i18n {
+        lang
+        locale
+        dir
+        currency
+      }
+    }
+  }
+}
+```
+
+That's not cached. The **labels** query (the big one with all your label names) is what's cached, and it only fires on a cache miss.
+
+---
+
+## Summary table
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Label renders as its own key name (`"Welcome_Text"`) | Unregistered manifest key | Add the key to `label-manifest.ts` |
+| Blank page after deploy | API-version mismatch (built against different org) | `sf config set target-org=<deploy-target>` before building |
+| Old translation persists after update | Stale localStorage cache | Clear `i18next_res_*` keys in DevTools, reload |
+
+---
+
+## Related problems (not silent-fail, but localization-adjacent)
+
+### Deploy rejected: "Not available for deploy for this organization"
+
+**Cause:** You're deploying a `<locale>.translation-meta.xml` for a language that isn't activated yet.
+
+**Fix:** Setup → Translation Workbench → Translation Settings → Add the language, then re-deploy.
+
+English never needs activation.
+
+---
+
+### Label shows in English when it should be translated (but not as a literal key)
+
+**Symptom:** The text is correct, just not translated (e.g., you see "Welcome" when you expected "Bienvenido").
+
+**Cause (most likely):** The translation file is missing that label, or its `<name>` doesn't match the `<fullName>` in `CustomLabels`. i18next falls back to the English base value (via `fallbackLng: "en"`), which is correct behavior; it just means that one key wasn't translated.
+
+**Other causes:**
+- The user's **Language** (not Locale) isn't set to the language you translated.
+- The translation file wasn't deployed (missing from `force-app/main/default/translations/`).
+
+**Check:** Setup → Translation Workbench → Translate → pick the language and the label. Is the translation there? If not, author it and re-deploy.
+
+---
+
+### Logged-in user sees their own language instead of the org default
+
+**Symptom:** In a B2X site (or any authenticated context), a logged-in user whose **Language** is French sees French text for a label you only authored in the org-default language (English), **even when the app requests English**. A guest user switching languages works fine; only the logged-in user with a different Language setting hits it.
+
+**Cause:** the server's label **fallback strategy**. When the app asks for a locale that has no explicit translation for a label, the server decides what to return. Its default strategy, `USER_DEFAULT`, resolves in this order: requested locale → that locale's language-fallback chain → **the logged-in user's own language** → the base/master value. Because the user's language comes *before* the base value, a French user gets French, not the English default.
+
+**Fix on the documented floor (11.42.1):** `SalesforceBackend` does not yet override the server's default, so the query resolves with `USER_DEFAULT` and a logged-in user with a different Language can still see their own language instead of the base value. To get the org default on this version, author an explicit org-default translation for the label, or debug the raw query with `fallback: BASE_VALUE` (shown below) to confirm the value you expect.
+
+> **Coming in a later SDK release:** a change that makes `SalesforceBackend` request `fallback: BASE_VALUE` is merged (2026-07-29) but not yet published, so it is not in 11.42.1. Once the release that carries it ships, the backend skips straight to the org-default value when a translation is missing, and you no longer need an explicit English translation just to work around this. Until then, treat the behavior above as current.
+
+**If you're debugging the raw labels query** (e.g., re-running it in DevTools): `fallback` must be declared in the operation signature (`$fallback: LabelFallback`) **and** passed to the `labels(...)` field. A `fallback` key in the variables block alone is silently dropped and the server falls back to `USER_DEFAULT`. It takes the `LabelFallback` enum (`USER_DEFAULT` / `BASE_VALUE` / `NONE`), not a locale string like `"en"`:
+
+```graphql
+query Labels($ns: String!, $names: [String!]!, $locale: String, $fallback: LabelFallback) {
+  uiapi {
+    platform {
+      labels(namespace: $ns, names: $names, locale: $locale, fallback: $fallback) {
+        name
+        value
+        resolvedLocale
+        wasFallback
+      }
+    }
+  }
+}
+```
+
+with `"fallback": "BASE_VALUE"` in the variables.
+
+---
+
+### Large manifest: no per-query limit to manage yourself
+
+**Symptom / worry:** You have hundreds of labels in one namespace and wonder whether you have to split the manifest or cap it.
+
+**You don't.** `uiapi.platform.labels` rejects any single call with more than 100 names, but `SalesforceBackend` handles this for you: it dedupes the names, splits each namespace into batches of at most 100, and issues those queries in parallel, then merges the results. A manifest with 500 `c:*` keys becomes 5 batched queries under the hood; your code and manifest stay flat.
+
+The load is **all-or-nothing per namespace**: if any batch fails, the whole namespace's read rejects (you don't get a half-populated namespace). If you're watching the Network tab, a large manifest is why you may see several `Labels` queries fire at once rather than one.
+
+---
+
+## Related
+
+- [i18n-setup.md](i18n-setup.md): the init file (where `expirationTime` is configured)
+- [label-xml.md](label-xml.md): Custom Labels + translations metadata
+- [interpolation.md](interpolation.md): `{0}/{1}` placeholders
+- [verifying.md](verifying.md): the serve/verify flow