@salesforce/afv-skills 1.50.0 → 1.52.0

package/skills/experience-ui-bundle-localize/references/{gotchas.md → common/gotchas.md}

@@ -8,7 +8,7 @@ These are localization-specific problems that fail **silently** (no console warn
 
 **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.
+**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 the i18n library, 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.
 
@@ -22,10 +22,9 @@ export const labelManifest = [
 ];
 ```
 
-```typescript
-// component
-const { t } = useTranslation("c");
-return <h1>{t("Welcome_Text")}</h1>; // renders "Welcome_Text" (literal string)
+```text
+// component calls the translation function with an unregistered key:
+translate("Welcome_Text")   // renders "Welcome_Text" (literal string)
 ```
 
 **Fix:** Add the missing key to `label-manifest.ts`:
@@ -37,11 +36,11 @@ export const labelManifest = [
 ];
 ```
 
-**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.
+**Why it's silent:** the i18n library (i18next, ngx-translate) is general-purpose. It doesn't know your labels come from Salesforce. When a key isn't in its cache, the fallback behavior (by 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:
+**Deeper detail:** The manifest is read by the label backend at boot (React's shipped `SalesforceBackend`, or Angular's custom `TranslateLoader`). It groups entries by namespace (all `c:*` together, all `LightningDatatable:*` together) and issues a GraphQL query per namespace:
 
 ```graphql
 query LoadLabels {
@@ -57,9 +56,9 @@ query LoadLabels {
 }
 ```
 
-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.
+If `Welcome_Text` isn't in the manifest, it isn't in the `names` array, so the server never returns it. The library's cache is empty for that key, and the translation 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.
+Within a namespace, the label backend 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.
 
 ---
 
@@ -74,7 +73,7 @@ Within a namespace, `SalesforceBackend` also splits the names into batches of at
 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.
+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 it mounts. You see a blank page.
 
 **Fix:** Before building, set the deploy target org as default so the versions match:
 
@@ -106,46 +105,30 @@ Look for `"API Version"` in the output (e.g., `63.0`).
 
 ---
 
-## 3. Stale localStorage cache → old translations persist
+## 3. Stale label 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)
+**Cause:** The i18n setup caches fetched labels so it doesn't hit GraphQL on every boot. Until that cache is invalidated, the app serves the cached copy and **never refetches**, so a fresh org value doesn't appear. The cache layer is **framework-specific**:
 
-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.
+- **React / i18next** persists labels to **localStorage** via `i18next-localstorage-backend`, chained in front of the network backend: `backends: [LocalStorageBackend, SalesforceBackend]`. Labels are keyed per language+namespace as `i18next_res_<lang>-<ns>` (e.g. `i18next_res_en-c`, `i18next_res_es-c`) with an `expirationTime` (default 24h / 86400000 ms). This survives reloads until it expires.
+- **Angular / ngx-translate** caches the resolved translations **in memory** on the `TranslateService` for the page session; the custom `TranslateLoader` re-issues the GraphQL query on the next `TranslateService.use(lang)` or a full page reload. A reload refetches (no persistent layer unless you add one).
 
-**What you see in DevTools:**
+**What you see in DevTools (React case):**
 - **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:
+**Fix:** Invalidate the cache, 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
+- **React / i18next:** DevTools → Application → Local Storage → your org's origin (e.g. `https://<org>.my.salesforce.app`) → delete the `i18next_res_*` keys (or **Clear site data**), then reload.
+- **Angular / ngx-translate:** a full page reload refetches; if you added a persistent cache layer, clear it too (**Clear site data**).
 
 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.
+**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 React 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.
+**Prevention:** When testing translation changes, habitually clear the cache before reloading. In React you can also lower `expirationTime` in the init file during development (e.g., 60000 = 1 minute), then 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:
 
@@ -174,7 +157,7 @@ That's not cached. The **labels** query (the big one with all your label names)
 |---|---|---|
 | 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 |
+| Old translation persists after update | Stale label cache | Clear the i18n cache (React: `i18next_res_*` in localStorage) and reload |
 
 ---
 
@@ -216,13 +199,13 @@ English never needs activation.
 
 **Symptom:** The URL or switcher displays a new site language, but labels remain in the previous language.
 
-**Cause:** B2C language context is established at boot from the language-specific route through `SFDC_ENV.language`. An in-place language change does not rebuild the SDK context, and `i18next_res_*` localStorage entries may continue serving cached labels.
+**Cause:** B2C language context is established at boot from the language-specific route through `SFDC_ENV.language`. An in-place language change does not rebuild the SDK context, and cached labels (React's `i18next_res_*` localStorage entries) may continue serving the old language.
 
-**Fix:** Make the switcher navigate to the configured language URL and perform a full page reload. Confirm the route and `SFDC_ENV.language` agree. During development, clear `i18next_res_*` before retesting.
+**Fix:** Make the switcher navigate to the configured language URL and perform a full page reload. Confirm the route and `SFDC_ENV.language` agree. During development, clear the i18n cache (React: `i18next_res_*`) before retesting.
 
 ### Choose fallback by bundle type
 
-The shipped `SalesforceBackend` supports `labelFallback`. Preserve its `BASE_VALUE` default for B2E by omitting the option. For B2C only, configure `labelFallback: "USER_DEFAULT"` so fallback follows the guest/site language context. Do not apply the B2C override to B2E.
+The label fetch supports `labelFallback`. Preserve its `BASE_VALUE` default for B2E (React: omit the option; Angular: pass `BASE_VALUE`). For B2C only, configure `labelFallback: "USER_DEFAULT"` so fallback follows the guest/site language context. Do not apply the B2C override to B2E.
 
 **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"`:
 
@@ -251,7 +234,7 @@ B2B remains unsupported. Do not infer B2B support from the B2C guidance or apply
 
 **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.
+**You don't.** `uiapi.platform.labels` rejects any single call with more than 100 names, but the label backend handles this for you (React's `SalesforceBackend`, or Angular's custom loader implementing the same logic): 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.
 
@@ -259,7 +242,8 @@ The load is **all-or-nothing per namespace**: if any batch fails, the whole name
 
 ## 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
+- `platform-sdk-i18n.md` (this folder): the shared runtime engine (Labels query, batching, fallback)
+- your framework reference's `i18n-setup.md`: the init file (where the cache is configured)
+- your framework reference's `interpolation.md`: `{0}/{1}` placeholders

package/skills/experience-ui-bundle-localize/references/{label-xml.md → common/label-xml.md}

@@ -34,7 +34,7 @@ This holds the **English base labels**: the source of truth for label content.
 
 | Field | Purpose | Notes |
 |---|---|---|
-| `<fullName>` | The label's API name | Used in `t("Key")` calls and the manifest (`"c:Welcome_Text"`). PascalCase, descriptive, unique. |
+| `<fullName>` | The label's API name | Used in translation calls (`"Key"`) and the manifest (`"c:Welcome_Text"`). PascalCase, descriptive, unique. |
 | `<language>` | Language code | Always `en_US` for the base label file. |
 | `<protected>` | Managed package protection | Always `false` for custom labels in your org (you can edit them). |
 | `<shortDescription>` | Internal description | For translators/developers, not shown to users. Describe what the label is for. |
@@ -61,6 +61,16 @@ Format: `<Context>_<Role>` in PascalCase with underscores between parts.
 
 One file per translated language (e.g., `es.translation-meta.xml` for Spanish, `fr.translation-meta.xml` for French, `ja.translation-meta.xml` for Japanese).
 
+🚫 **Custom Label translations use the `Translations` metadata type — never `CustomObjectTranslation`.**
+Write them to `force-app/main/default/translations/<locale>.translation-meta.xml` with a
+`<Translations>` root. Do **not** author them as
+`objectTranslations/CustomLabels-<locale>/CustomLabels-<locale>.objectTranslation-meta.xml` with a
+`<CustomObjectTranslation>` root — that type is for translating **custom-object components** (field
+labels, record types, picklist values), not org-level Custom Labels, and deploying labels that way
+fails. If you catch yourself reaching for `objectTranslations/` or `CustomObjectTranslation` for a
+Custom Label, stop: the correct target is the `translations/<locale>.translation-meta.xml` file
+described here.
+
 ### Structure
 
 ```xml
@@ -77,6 +87,8 @@ One file per translated language (e.g., `es.translation-meta.xml` for Spanish, `
 </Translations>
 ```
 
+⚠️ Inside `<Translations>`, the translated text goes in **`<label>`**, never `<value>`. `<value>` is the *CustomLabels* element (it belongs in `CustomLabels.labels-meta.xml`); using it inside a `<customLabels>` block here produces malformed metadata that fails validation. Each `<customLabels>` block contains exactly `<label>` and `<name>` — nothing else.
+
 Always write the whole document shown above, not a fragment: exactly one XML declaration, one `<Translations>` root with the Metadata API namespace, and one complete `<customLabels>` block per label. For an untranslated scaffold, copy the XML-escaped English source text into `<label>` and leave actual translation to the localization team. Preserve positional placeholders such as `{0}` and `{1}`.
 
 XML-escape text values: `&` becomes `&amp;`, `<` becomes `&lt;`, and `>` becomes `&gt;`. Before considering the file complete, parse both `CustomLabels.labels-meta.xml` and every generated `*.translation-meta.xml` with an XML parser. A fragment with balanced-looking inner tags is still invalid without its root document.
@@ -151,7 +163,7 @@ export const labelManifest = [
 
 Other namespaces exist (e.g., `LightningDatatable` for framework-shipped labels), but most bundles only use `c`.
 
-In component code, the namespace is usually implicit (set via `defaultNS: "c"` in the init), so you call `t("Welcome_Text")` not `t("c:Welcome_Text")`.
+In component code the namespace is usually implicit (the init sets `c` as the default), so you call your framework's translation function with the bare key (`Welcome_Text`), not `c:Welcome_Text`. The exact call convention is in your framework reference's `localize.md`.
 
 ---
 
@@ -169,13 +181,15 @@ Labels can include **positional placeholders** for runtime substitution:
 </labels>
 ```
 
-At call time:
+At call time, your framework's translation function substitutes the positional values:
 
-```typescript
-t("Save_Failed_Message", { 0: "Account", 1: "Permission denied" });
+```text
+translate("Save_Failed_Message", { 0: "Account", 1: "Permission denied" })
 // → "Failed to save Account: Permission denied"
 ```
 
+(The exact call syntax is framework-specific — see your framework reference's `interpolation.md`.)
+
 **Translations must preserve the placeholders:**
 
 ```xml
@@ -186,9 +200,9 @@ t("Save_Failed_Message", { 0: "Account", 1: "Permission denied" });
 </customLabels>
 ```
 
-The placeholders can move (Spanish grammar might flip the order), but they must stay as `{0}`, `{1}`; i18next does the substitution at render time.
+The placeholders can move (Spanish grammar might flip the order), but they must stay as `{0}`, `{1}`; the i18n library does the substitution at render time.
 
-See [interpolation.md](interpolation.md) for how this works under the hood.
+See your framework reference's `interpolation.md` for how this works under the hood.
 
 ---
 
@@ -259,14 +273,9 @@ export const labelManifest = ["c:Welcome_Text"];
 
 ### 4. Use in a component
 
-```typescript
-import { useTranslation } from "react-i18next";
-
-function WelcomeBanner() {
-  const { t } = useTranslation("c");
-  return <h1>{t("Welcome_Text")}</h1>;
-}
-```
+Replace the hardcoded string with your framework's translation call (referencing the key by
+its bare `<fullName>`). The exact call convention — the import/injection and the function
+name — is in your framework reference's `localize.md`.
 
 ### 5. Deploy
 
@@ -290,7 +299,8 @@ Review the exact paths and target org with the user before deploying. Repeat the
 
 ## Related
 
-- [i18n-setup.md](i18n-setup.md): the init file + manifest wiring
-- [interpolation.md](interpolation.md): how `{0}/{1}` substitution works
+- `platform-sdk-i18n.md` (this folder): the shared runtime engine that fetches these labels
 - [verifying.md](verifying.md): the serve/verify flow
 - [gotchas.md](gotchas.md): silent-fail traps
+- your framework reference's `i18n-setup.md`: the init file + manifest wiring
+- your framework reference's `interpolation.md`: how `{0}/{1}` substitution works

package/skills/experience-ui-bundle-localize/references/common/platform-sdk-i18n.md

@@ -0,0 +1,169 @@
+# The Platform SDK i18n engine (framework-neutral)
+
+The runtime plumbing that resolves Salesforce Custom Labels for a UI Bundle is **the same
+regardless of framework**. It ships in `@salesforce/platform-sdk` (the `/i18n` subpath) and is
+what both the React (i18next) and Angular (ngx-translate) paths build on. This file documents
+that shared engine once; each framework reference only covers how it wires the engine into its
+own i18n library.
+
+A UI Bundle can't use compile-time `@salesforce/label/*` imports the way LWC does (those resolve
+inside the platform compiler your standalone bundle skips). Instead the app **fetches labels at
+runtime** over the Salesforce GraphQL UI API and hands them to a standard i18n library to render.
+
+---
+
+## What the SDK gives you (you don't write these)
+
+From `@salesforce/platform-sdk` (package root):
+
+- `createDataSDK()` → returns a `DataSDK` whose `.graphql.query(...)` surface talks to the org.
+  Its `query` **never rejects**; transport/GraphQL errors come back on `result.errors`.
+
+From `@salesforce/platform-sdk/i18n`:
+
+- `fetchI18nContext(dataSDK)` — reads the user's locale context (below). **Memoized** for the page.
+- `reloadI18nContext(dataSDK)` — clears that memo and re-fetches (for in-session locale changes).
+- `createSalesforceDetector(dataSDK)` — an i18next-shaped language detector whose `detect()`
+  returns the cached context's `lang`. (React consumes this directly; Angular reads `ctx.lang`
+  from `fetchI18nContext` instead and calls `TranslateService.use(lang)`.)
+- `SalesforceBackend` — an **i18next backend plugin** that fetches labels over GraphQL. React
+  plugs it straight into i18next. Angular does **not** use it; its custom `TranslateLoader`
+  re-implements the same GraphQL fetch (same query, same batching) against ngx-translate's
+  `Observable` contract.
+- `createI18nFormatters(ctx)` — Intl wrappers (`formatDate`, `formatNumber`, `formatCurrency`).
+
+You write only two thin files per app: the **init/loader wiring** (framework-specific) and the
+**label manifest** (framework-neutral format, below).
+
+---
+
+## The label fetch: `uiapi.platform.labels`
+
+Both frameworks issue the same GraphQL query to resolve labels for a language + namespace:
+
+```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
+      }
+    }
+  }
+}
+```
+
+- `ns` — the namespace (`c` for your org's custom labels; also e.g. `LightningDatatable`).
+- `names` — the label API names in that namespace (no `ns:` prefix here).
+- `locale` — the target language (the user's `lang`, or a B2C site language).
+- `fallback` — a `LabelFallback` enum value (below).
+
+The result is assembled into a plain `Record<string, string>` of `{ [label.name]: label.value }`.
+**Labels whose `value` is null are skipped** (not added to the map), so an unresolved key falls
+through to the i18n library's key-name fallback.
+
+### Manifest → namespaces → batches
+
+The **label manifest** is a flat array of `"namespace:key"` strings you maintain by hand:
+
+```typescript
+// src/i18n/label-manifest.ts
+export const labelManifest = [
+  "c:Welcome_Text",
+  "c:Save_Button",
+  "LightningDatatable:sort",
+];
+```
+
+The backend/loader:
+1. Splits each entry on the first `:` and **groups by namespace** (`{ c: [...], LightningDatatable: [...] }`).
+2. For each namespace + language, **dedupes** the names and **chunks them into batches of at most
+   100** (`uiapi.platform.labels` rejects a single call with > 100 names).
+3. Fires the batches **in parallel** and merges the results. The load is **all-or-nothing per
+   namespace**: if any batch rejects, the whole namespace read fails (no half-populated namespace).
+
+A manifest with 500 `c:*` keys becomes 5 batched queries under the hood; your manifest stays flat.
+
+### `LabelFallback` — pick by bundle type
+
+```typescript
+type LabelFallback = "BASE_VALUE" | "USER_DEFAULT" | "NONE";   // default: BASE_VALUE
+```
+
+- **B2E** — keep the `BASE_VALUE` default (a registered key with no translation for the active
+  language resolves to its English base value; `wasFallback: true`).
+- **B2C** — set `labelFallback: "USER_DEFAULT"` so fallback follows the guest/site language context.
+- Never apply the B2C override to B2E.
+
+(When re-running the query by hand in DevTools, `$fallback` must be declared in the operation
+signature **and** passed to the `labels(...)` field — a `fallback` key in the variables block alone
+is silently dropped and the server defaults to `USER_DEFAULT`.)
+
+---
+
+## The locale context: `fetchI18nContext`
+
+A separate, small GraphQL query reads the user's locale context. It runs on every boot (it is
+**not** cached in localStorage — only memoized in module memory for the page lifetime):
+
+```graphql
+query I18nDetect {
+  uiapi { platform { i18n { lang locale dir currency timeZone } } }
+}
+```
+
+```typescript
+interface I18nContext { lang; locale; dir; currency; timeZone; }
+```
+
+- `lang` — the **translation** axis (`en_US`, `es`, `de`) → picks which label translations load.
+- `locale` — the **formatting** axis (`de_DE`, `fr_CA`) → feeds `Intl` formatters. Region-only;
+  it does **not** flip label text.
+- `dir` — `"ltr"` / `"rtl"` (set `document.documentElement.dir` at boot).
+
+At boot each framework: `await fetchI18nContext(dataSDK)`, then sets `document.documentElement.dir`
+and `.lang`, and tells its i18n library which language to use. `reloadI18nContext(dataSDK)` is the
+only way to pick up an in-session locale change (a fresh `fetchI18nContext` returns the memo).
+
+### Formatting: `createI18nFormatters(ctx)`
+
+Returns `{ formatDate, formatNumber, formatCurrency }` bound to `ctx.locale` (BCP-47),
+`ctx.currency`, and `ctx.timeZone`, wrapping `Intl.*`. Note it formats off `ctx.locale` (region),
+**not** `ctx.lang` (translation). Positional `{0}/{1}` interpolation does **not** format values —
+pass an already-formatted string as the placeholder value if you need locale-aware numbers/dates.
+
+---
+
+## Runtime floor & dependency alignment
+
+- The `platform.labels` runtime path for UI Bundles ships in **Salesforce Release 264 / API v68.0**.
+  A `sourceApiVersion` in `sfdx-project.json` records what you *declared*, not what the org
+  *supports* — query the org's actual max API version before wiring (`check-org-api-version.sh`,
+  precondition 4). Below v68.0 a localized bundle renders blank or shows raw key names.
+- Keep the Platform SDK, UI Bundle, and build-plugin siblings aligned and **≥ 11.49.3**.
+
+---
+
+## How each framework consumes this engine
+
+| Concern | React (i18next) | Angular (ngx-translate) |
+|---|---|---|
+| Label fetch | `SalesforceBackend` (shipped) in a chained backend | custom `TranslateLoader.getTranslation(lang)` issuing the same query |
+| Language pick | `createSalesforceDetector(dataSDK)` | read `ctx.lang`, call `TranslateService.use(lang)` |
+| Cache | `i18next-localstorage-backend` (`i18next_res_*`, 24h) | in-memory on `TranslateService` (reload refetches) |
+| Interpolation | `interpolation: { prefix:"{", suffix:"}" }` for `{0}/{1}` | custom `TranslateParser`/compiler for `{0}/{1}` |
+
+See your framework reference's `i18n-setup.md` for the exact wiring, and [gotchas.md](gotchas.md)
+for the silent-fail traps this engine can produce.
+
+---
+
+## Related
+
+- [label-xml.md](label-xml.md): the Custom Labels + translations metadata this engine resolves
+- [verifying.md](verifying.md): build/deploy/verify labels across locales
+- [gotchas.md](gotchas.md): unregistered keys, API-version bake-in, stale cache, B2C 403
+- your framework reference's `i18n-setup.md` / `interpolation.md`: the framework-specific wiring

package/skills/experience-ui-bundle-localize/references/{verifying.md → common/verifying.md}

@@ -15,6 +15,19 @@ Authenticated B2E verification has five steps:
 
 B2C verification uses the site-configured languages and language-specific URLs instead of the authenticated user's Language setting. Follow the B2C section after deployment.
 
+### What this skill produces vs. what's left for you / other skills
+
+When asked "what's left to deploy," answer with these — do **not** invent new metadata types:
+
+- **This skill already wrote** the deployable metadata: `CustomLabels.labels-meta.xml` (English base)
+  and `translations/<locale>.translation-meta.xml` (the `Translations` type — **not**
+  `CustomObjectTranslation`; see [label-xml.md](label-xml.md)), plus the i18n wiring and manifest.
+- **Manual/admin prerequisite (not a deployable file this skill emits):** activate each non-English
+  language in Translation Workbench (Step 2) — otherwise the deploy is rejected. There is no
+  "language settings" file for this skill to generate.
+- **Delegated to other skills:** Experience Cloud **site languages** / `sfdc_cms__languageSettings`
+  → `experience-ui-bundle-site-generate`; the **deploy** itself → `experience-ui-bundle-deploy`.
+
 ---
 
 ## Step 1: Build the app
@@ -132,10 +145,10 @@ This step is for **B2E only**. For B2C, use the site language route below.
 3. If the configured language or deployed metadata requires publishing, treat publication as a separate go-live mutation. Resolve the site's `Network.Name` from the target site (prefer matching its `UrlPathPrefix`), show that community name and target org, and wait for explicit user confirmation immediately before running `sf community publish --name "<network-name>" --target-org <org-alias>`. A metadata deployment is not publication approval. Track the returned background operation to completion before guest verification; if propagation is still in progress, report that instead of treating stale output as a localization failure.
 4. Open the published site as a signed-out guest through its language-specific URL. Confirm the boot environment exposes the same language in `SFDC_ENV.language`.
 5. Confirm translated labels render and the labels GraphQL request succeeds for the guest.
-6. Use the site's language switcher. It must navigate to the target language URL and cause a **full page reload**; changing i18next in place leaves the boot-time SDK context and cached resources stale.
+6. Use the site's language switcher. It must navigate to the target language URL and cause a **full page reload**; changing the i18n library's language in place leaves the boot-time SDK context and cached resources stale.
 7. Confirm the new route and `SFDC_ENV.language` agree, then verify the translated labels again.
 
-For a localized local preview, supply an explicit configured language in the preview URL/route. Do not use the authenticated org user's Language as evidence for guest behavior. If a recent translation or route change appears stale, delete `i18next_res_*` localStorage entries and reload each language URL.
+For a localized local preview, supply an explicit configured language in the preview URL/route. Do not use the authenticated org user's Language as evidence for guest behavior. If a recent translation or route change appears stale, clear your i18n library's cached labels and reload each language URL (the exact cache keys are in your framework reference's `gotchas.md`).
 
 ---
 
@@ -162,7 +175,7 @@ When you test localization, **change the Language**, not the Locale. Changing Lo
 
 **Check:** Go to Setup → Translation Workbench → Translate → pick the language and the label. Is the translation there? If not, author it and re-deploy.
 
-**Fallback behavior:** If a registered key is untranslated for the active language, the Platform SDK's GraphQL request resolves it according to `labelFallback`: B2E uses `BASE_VALUE`; B2C explicitly uses `USER_DEFAULT`. The i18next `fallbackLng` applies only if no resource is loaded for the detected language; it does not define Salesforce label-resolution semantics.
+**Fallback behavior:** If a registered key is untranslated for the active language, the Platform SDK's GraphQL request resolves it according to `labelFallback`: B2E uses `BASE_VALUE`; B2C explicitly uses `USER_DEFAULT`. Your i18n library's own language fallback (i18next's `fallbackLng`, ngx-translate's `fallbackLang` — `defaultLanguage` in ngx-translate majors before v16) applies only if no resource is loaded for the detected language; it does not define Salesforce label-resolution semantics.
 
 ---
 
@@ -170,7 +183,7 @@ When you test localization, **change the Language**, not the Locale. Changing Lo
 
 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 listed in the manifest, so an unregistered key is **never requested**, and i18next, finding nothing, renders the key string. **No console warning, no error**; it fails silently.
+**Cause:** The key isn't in your `label-manifest.ts`. The app only fetches labels listed in the manifest, so an unregistered key is **never requested**, and the i18n library, finding nothing, renders the key string. **No console warning, no error**; it fails silently.
 
 **Fix:** Add the `"c:Key"` entry to `label-manifest.ts` (Step 3 of the workflow). This is the most common localization bug; if a label looks wrong, check the manifest first.
 
@@ -182,17 +195,13 @@ See [gotchas.md](gotchas.md) for the full explanation.
 
 You edited a label in the Translation Workbench (or redeployed a `translation-meta.xml`), confirmed the new value is in the org, but the app keeps rendering the **previous** value on reload.
 
-**Cause:** The label cache. Your `src/i18n/index.ts` chains two backends, `[LocalStorageBackend, SalesforceBackend]`, so on load i18next reads labels from **localStorage first** and only falls through to GraphQL on a cache miss. Labels are cached per language+namespace under keys like `i18next_res_de-c` (DevTools → Application → Local Storage), with a 24-hour `expirationTime`. Until that entry expires, your app serves the cached copy and never refetches.
+**Cause:** The label cache. To avoid a GraphQL roundtrip on every boot, the i18n setup caches fetched labels client-side (typically in `localStorage`) per language+namespace, with an expiration window (commonly 24 hours). Until that entry expires, your app serves the cached copy and never refetches — so a fresh org value doesn't appear.
 
-**Fix:** Clear the cached labels, then reload:
-- **DevTools → Application → Local Storage** → delete the `i18next_res_*` keys
-- Or **Clear site data** to wipe everything
+**Fix:** Clear the cached labels, then reload (**DevTools → Application → Local Storage** → delete the cached label entries, or **Clear site data** to wipe everything). The next load misses the cache, refetches over GraphQL, and shows the current value. The **exact cache keys and where they live are framework-specific** — see your framework reference's `gotchas.md` (e.g. React/i18next uses `i18next_res_*`).
 
-The next load misses the cache, refetches over GraphQL, and shows the current value.
+**This is expected behavior, not a bug.** The cache is what makes labels fast after first load. In production, a translation change takes up to the expiration window to roll out; during development, clear the cache to see edits immediately.
 
-**This is expected behavior, not a bug.** The cache is what makes labels fast after first load. In production, a translation change takes up to `expirationTime` (24 hours) to roll out; during development, clear the cache to see edits immediately.
-
-See [gotchas.md](gotchas.md) for the full explanation.
+See your framework reference's `gotchas.md` for the full explanation.
 
 ---
 
@@ -200,7 +209,7 @@ See [gotchas.md](gotchas.md) for the full explanation.
 
 This is expected, not a bug, **as long as you only authored the base (`en_US`) translation.**
 
-For B2E, the shipped `SalesforceBackend` default is `BASE_VALUE`. The GraphQL server returns the label's base value for a regional Language with no explicit translation: `resolvedLocale` comes back as the base (`en_US`) with `wasFallback: true`. The server does **not** map `en_GB → en_US` region-aware; it honors the base-value fallback.
+For B2E, the label fetch default is `BASE_VALUE`. The GraphQL server returns the label's base value for a regional Language with no explicit translation: `resolvedLocale` comes back as the base (`en_US`) with `wasFallback: true`. The server does **not** map `en_GB → en_US` region-aware; it honors the base-value fallback.
 
 **Fix (only if you want region-specific text):** Author a translation for that exact regional Language (`en_GB.translation-meta.xml`). Otherwise the base value is the intended, correct result.
 
@@ -218,7 +227,7 @@ Use this to confirm everything works:
 - [ ] Opened at `lightning.force.com/lwr/application/ai/<namespace>-<bundleName>` (redirected to `.my.salesforce.app` is fine)
 - [ ] Changed user's **Language** (not Locale) to the translated language
 - [ ] Reloaded, labels render in the new language
-- [ ] If labels are stale, cleared `i18next_res_*` from localStorage
+- [ ] If labels are stale, cleared the i18n library's cached labels from localStorage (see your framework `gotchas.md`)
 - [ ] B2C: site languages are configured/published and the language URL matches `SFDC_ENV.language`
 - [ ] B2C: any site publication received separate explicit confirmation for the named site and org
 - [ ] B2C: signed-out guest labels GraphQL succeeds (no HTTP 403)
@@ -241,7 +250,8 @@ Use this to confirm everything works:
 
 ## Related
 
-- [i18n-setup.md](i18n-setup.md): the init file + manifest
 - [label-xml.md](label-xml.md): Custom Labels + translations metadata
-- [interpolation.md](interpolation.md): `{0}/{1}` placeholders
 - [gotchas.md](gotchas.md): silent-fail traps (unregistered keys, stale cache, API-version mismatch)
+- `platform-sdk-i18n.md` (this folder): the shared runtime engine (Labels query, fallback)
+- your framework reference's `i18n-setup.md`: the init file + manifest
+- your framework reference's `interpolation.md`: `{0}/{1}` placeholders

package/skills/experience-ui-bundle-localize/{scripts → references/react}/check-i18n-wired.sh

@@ -1,7 +1,12 @@
 #!/usr/bin/env bash
 set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipeline failures (-o pipefail)
 #
-# check-i18n-wired.sh — Confirm the i18n init exists and is called at boot.
+# check-i18n-wired.sh — Confirm the React i18next init exists and is called at boot.
+#
+# React-specific: the manifest -> backendOptions / SalesforceBackend detection is
+# i18next-shaped and has no ngx-translate analog, so this script lives under the
+# React reference (references/react/) rather than the shared scripts/ folder. The
+# Angular equivalent is authored separately under references/angular/.
 #
 # Whether the app already has i18n wiring is a file-existence plus call-site
 # check, so run this rather than reading for it by hand. It looks for an init
@@ -9,7 +14,7 @@ set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipe
 # file.
 #
 # Usage (run from the UI bundle dir, or pass its src path):
-#   bash <skill-dir>/scripts/check-i18n-wired.sh [src-dir]
+#   bash <skill-dir>/references/react/check-i18n-wired.sh [src-dir]
 #
 # src-dir defaults to "src".
 #
@@ -23,7 +28,7 @@ set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipe
 #   0  fully wired — initI18n() defined, called at boot, AND the manifest is
 #      passed into the SalesforceBackend's backendOptions. Just add new keys.
 #   1  no i18n init found — no initI18n() definition. Scaffold the whole setup
-#      (see references/i18n-setup.md).
+#      (see references/react/i18n-setup.md).
 #   2  init defined but not called at boot — add only the boot-time initI18n()
 #      call in the entry file; do NOT re-scaffold or overwrite the init.
 #   3  wired at boot but the manifest could not be confirmed as passed into the