@salesforce/afv-skills 1.50.0 → 1.52.0

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

@@ -1,8 +1,8 @@
 ---
 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 labels for another language, 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 B2E UI Bundles and B2C site bundles. Use experience-ui-bundle-site-generate instead for site language configuration or sfdc_cms__languageSettings. DO NOT TRIGGER for B2B site bundles, 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."
+description: "MUST activate to localize / internationalize a uiBundles/*/src/ project (React or Angular): extract hardcoded user-facing strings into Custom Labels, wire a runtime i18n library over the Platform SDK backend, add labels for another language, or troubleshoot label rendering across locales. Triggers: user-facing string literals in component files, a CustomLabels.labels-meta.xml, a src/i18n/ directory or label-manifest.ts, translation call sites, or requests to 'translate / localize / internationalize / support another language.' Scope: authenticated B2E UI Bundles and B2C site bundles. Use experience-ui-bundle-site-generate instead for site language configuration or sfdc_cms__languageSettings. DO NOT TRIGGER for B2B site bundles, 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"
+  version: "1.2"
   domains: ["Experience"]
   minApiVersion: "68.0"
   relatedSkills:
@@ -19,30 +19,26 @@ metadata:
       semver: ">=2.0.0"
 ---
 
-# Localize a React UI Bundle
+# Localize a UI Bundle
 
-Localize a React UI Bundle: extract user-facing strings into Salesforce Custom Labels, wire i18next over the Platform SDK GraphQL backend, and verify labels across locales.
+Localize a UI Bundle: extract user-facing strings into Salesforce Custom Labels, wire a
+runtime i18n library over the Platform SDK backend, and verify labels 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
+This file is the **framework-neutral workflow + guardrail spine**. The framework-specific
+detail — which i18n library, the translation call convention, the files scanned, the wiring
+shape, and the depth docs — lives in a per-framework reference.
 
 ## 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
-}
-```
+A UI Bundle can't use compile-time label imports the way LWC does (`@salesforce/label/*`
+resolves inside the platform's compiler, which your standalone bundle doesn't go through).
+Instead, your app **fetches labels at runtime** through the Salesforce GraphQL UI API and
+hands them to a standard i18n library to render. The Platform SDK provides the runtime
+plumbing: 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 your i18n library, and a manifest listing which labels your app uses — then
+author the labels themselves as Salesforce Custom Labels metadata. The exact library and
+call convention are framework-specific; see your framework reference.
 
 ---
 
@@ -53,7 +49,46 @@ function WelcomeBanner() {
 | Bundle doesn't exist yet | **experience-ui-bundle-frontend-generate** skill |
 | Deploying the app with its labels | **experience-ui-bundle-deploy** skill |
 | Configuring site languages or `sfdc_cms__languageSettings` | **experience-ui-bundle-site-generate** skill |
-| Localizing an existing bundle | **Workflow below** |
+| Localizing an existing bundle | **Determine the framework (below), then the workflow** |
+
+**Determine the framework.** It is normally already decided by the calling context — passed
+down by the coordinator skill that invoked this one, or stated in the user's request. Use that.
+
+The frameworks this skill supports are exactly the reference folders under
+`<SKILL_DIR>/references/`, each containing a `localize.md` (so `react` →
+`<SKILL_DIR>/references/react/localize.md`). This is the single source of truth — adding a
+framework means adding a reference folder, nothing here changes.
+
+- **If the framework is known** — open `<SKILL_DIR>/references/<framework>/localize.md` and
+  keep it alongside this spine. It supplies the library, the call convention, the files to
+  scan, and the wiring code.
+- **If it is unknown** (a standalone run where nobody said which) — run the deterministic
+  detector on the app / uiBundle root before asking anyone:
+
+  ```bash
+  bash "<SKILL_DIR>/scripts/detect-framework.sh" "<app-or-uiBundle-root>"
+  ```
+
+  It combines an `angular.json` at/above the root, `@angular/core` / `react` in any
+  non-`node_modules` `package.json`, and source-file signatures, then prints one token and
+  sets a matching exit code:
+  - `react` or `angular` (exit 0) → use that framework. **Do not ask the user** — the
+    detection is deterministic. Open `<SKILL_DIR>/references/<framework>/localize.md`.
+  - `ambiguous` (exit 2) → both frameworks are present. List `<SKILL_DIR>/references/` and ask
+    the user which one to localize. If they name a framework with no matching reference folder,
+    it is not supported here — stop.
+  - `unknown` (exit 3) → **no supported framework detected. Terminate the workflow.** Do not
+    guess and do not proceed: report that neither React nor Angular signals were found in the
+    bundle, so localization cannot continue, and stop here.
+
+Throughout the steps below, `<framework>` means the folder chosen here. The deterministic
+check scripts split by coupling:
+- **Framework-neutral, shared in `<SKILL_DIR>/scripts/`** — `detect-framework.sh` (the Step-0
+  detector above), `check-org-api-version.sh` and `detect-bundle-type.sh` (pure org/metadata
+  checks), and `check-manifest-registered.sh` (agnostic skeleton; it takes `--framework
+  <framework>` to select the call-site grammar).
+- **Framework-specific, under `<SKILL_DIR>/references/<framework>/`** — `check-i18n-wired.sh`
+  (its manifest-into-backend detection is i18n-library-shaped, so each framework ships its own).
 
 ---
 
@@ -61,9 +96,9 @@ function WelcomeBanner() {
 
 | # | 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 | Platform SDK, UI Bundle, and Vite plugin siblings installed and aligned (≥11.49.3) | `package.json` in the UI bundle dir | Tell user to align and upgrade them; 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 |
+| 1 | It's a `uiBundles/*/src/` project (React or Angular) | Project structure matches | Not a UI Bundle → route to the correct skill |
+| 2 | Platform SDK, UI Bundle, and build-plugin siblings installed and aligned (≥11.49.3) | `package.json` in the UI bundle dir | Tell user to align and upgrade them; cannot proceed |
+| 3 | You can identify where the app mounts | Read the entry file (see the framework reference) | 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 authenticated B2E or the request/context explicitly identifies a B2C site, not B2B | Run the bundle-type detection below and use the request/context for site product identity | Explicit B2B → reject; site type not explicit → ask the user and stop until confirmed; B2C also requires precondition 6 |
 | 6 | For B2C only, an admin has enabled `GraphQLApiOrgPrefForGuestUsers` | Ask the admin to confirm the org preference is already enabled | Do not enable it; explain that guest GraphQL returns HTTP 403 without it and stop (dependency: W-23854208) |
@@ -71,15 +106,15 @@ function WelcomeBanner() {
 **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>
+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.)
 
-**Bundle-type detection (precondition 5).** The bundle's type decides which localization branch applies. Pass the full path to the bundle dir; the script derives the metadata root from it, so the current directory does not matter:
+**Bundle-type detection (precondition 5).** The bundle's type decides which localization branch applies. It is framework-agnostic (pure Salesforce metadata). 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>
+bash <SKILL_DIR>/scripts/detect-bundle-type.sh <path-to-uiBundles/<name>/ dir>
 ```
 
 Act on the exit-code contract: `0` → authenticated app (B2E or in-core internal), use the B2E branch; `10` → bound public site app-container candidate, meaning metadata proves site binding and guest access but **not** B2C versus B2B; `11` → bound non-public/unsupported site, stop; `12` → both CustomApplication and one site binding exist, ask which runtime context is the localization target; `13` → multiple matching Experience site bindings, show the reported site names and ask which site/runtime context is the target; `2` → unbound/unknown, report the script output and stop rather than guessing.
@@ -94,14 +129,17 @@ If a precondition isn't met, stop: report the specific block to the user and rec
 
 ## Workflow: the five steps
 
-Each step has a **completion criterion** and a **confirm-before-continue** pause.
+Each step has a **completion criterion** and a **confirm-before-continue** pause. Framework
+specifics (file extensions, the translation call, the install, the init code) come from
+`<SKILL_DIR>/references/<framework>/localize.md`.
 
 ### Step 1: Detect
 
-**Goal:** Scan `.tsx`/`.jsx` files for user-facing hardcoded strings.
+**Goal:** Scan the framework's component files for user-facing hardcoded strings. (The
+framework reference names the file extensions to scan.)
 
 **What to scan:**
-- String literals inside JSX tags: `<h1>Welcome</h1>` → candidate
+- String literals shown to users in markup: `Welcome` in a heading → 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)
 
@@ -110,12 +148,12 @@ Each step has a **completion criterion** and a **confirm-before-continue** pause
 - Object keys / property names
 - `data-*` attributes (machine-readable)
 - Test IDs (`data-testid`, `id` attributes)
-- Text already wrapped in `t()` calls
+- Text already wrapped in a translation call
 - 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
+1. Scan the `src/` directory for the framework's component files
 2. Extract candidates, showing file path + line number for each
 3. Show the list to the developer
 
@@ -128,7 +166,7 @@ Developer confirms the list (or edits it to remove false positives).
 
 ### Step 2: Extract
 
-**Goal:** For each confirmed string, add a Custom Label and replace the JSX literal with a `t()` call.
+**Goal:** For each confirmed string, add a Custom Label and replace the literal with a translation 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.
@@ -142,24 +180,20 @@ Developer confirms the list (or edits it to remove false positives).
      <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.
+   (Full XML structure: `references/common/label-xml.md`)
+3. **Replace the string** in the component with your framework's translation call, and add
+   any required import/injection. The exact call convention is in the framework reference.
 
 **Completion criterion:**
-Every confirmed string has both a `CustomLabels` entry and a `t()` call in its original location.
+Every confirmed string has both a `CustomLabels` entry and a translation 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]"
+**Pause:** "For each string I'll add a Custom Label and replace the literal with a translation call. 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.
+**Goal:** Add each key to the label manifest so the i18n runtime knows to fetch it.
 
 **Action:**
 1. Add each key to the manifest array in `src/i18n/label-manifest.ts`:
@@ -173,14 +207,14 @@ Every confirmed string has both a `CustomLabels` entry and a `t()` call in its o
    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.
+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 translation call site against the manifest and treats a missing `label-manifest.ts` (when call sites 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
+bash <SKILL_DIR>/scripts/check-manifest-registered.sh --framework <framework>
 ```
 
-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.
+Branch on the exit code: `0`, every key is registered (or there are no call sites 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]."
 
@@ -188,48 +222,32 @@ Branch on the exit code: `0`, every key is registered (or there are no `t()` cal
 
 ### Step 4: Wire
 
-**Goal:** Ensure the i18next init exists; scaffold it if the app has no i18n yet.
-
-Configure `SalesforceBackend` by bundle type: preserve the shipped `BASE_VALUE` default for B2E; for B2C only, set `labelFallback: "USER_DEFAULT"` and pass the route-selected `SFDC_ENV.language`, with `ctx.lang` fallback, as `lng` to `i18next.init`. See [references/i18n-setup.md](references/i18n-setup.md) for both configurations and B2C language context.
+**Goal:** Ensure the i18n wiring exists; scaffold it if the app has no i18n yet. The install
+command, the wiring code, and the B2E vs B2C fallback configuration are all in the framework
+reference (`references/<framework>/localize.md` and its `i18n-setup.md`).
 
 **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.
+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 the framework's i18n wiring (React: an `initI18n()` init file called at boot; Angular: `provideTranslateService`/`TranslateModule.forRoot` registering a custom `TranslateLoader`, loaded at boot via `TranslateService.use`), and when that exists it also reports whether the label manifest is imported and actually reaches the label backend/loader. 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
+bash <SKILL_DIR>/references/<framework>/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
-   });
-   ```
+- Exit `0` → fully wired, the manifest reaches the label backend/loader; just add new keys.
+- Exit `1` → no i18n wiring exists; scaffold the whole setup per the framework reference.
+- Exit `2` → the wiring exists but is incomplete (React: init not called at boot; Angular: loader not registered, or registered but no boot-time `TranslateService.use`); do **not** re-scaffold or overwrite it. Add only the missing wiring the message names, then re-run.
+- Exit `3` → wired at boot but the script **could not confirm** the manifest reaches the backend/loader. This last check is a textual heuristic: the manifest may be wired through a variable, spread, factory, 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 before reconciling; never re-scaffold 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 wiring" result; do not scaffold. Fix the path and re-run.
 
-**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.
+**B2C override — applies even at exit `0`:** the wiring check only proves i18n *exists*, not that it is correct for B2C. A seed with B2E wiring — `dir = ctx.dir` and a loader with **no** `labelFallback` — passes `check-i18n-wired.sh` at exit `0` but is **wrong for a B2C site**. If the site is B2C, don't stop at "add new keys": open `src/i18n/index.ts` (or the framework's init file) and, using `resolvedLang` (= `SFDC_ENV.language || ctx.lang`; the detector does not read `SFDC_ENV.language`), (a) add `labelFallback: "USER_DEFAULT"`, (b) set direction from it — `i18next.dir(resolvedLang)`, never `ctx.dir`, and (c) initialize in it — React `lng: resolvedLang` in `i18next.init`; Angular `translate.use(resolvedLang)`. See `references/<framework>/i18n-setup.md`. Never leave B2E wiring on a B2C site.
 
 **Completion criterion:**
-`initI18n()` exists and is called once at boot; the manifest is wired into the backend.
+The i18n wiring exists and is called once at boot; the manifest reaches the label backend/loader. For B2C, all three `resolvedLang` overrides are applied — `USER_DEFAULT` fallback, display language (React `lng`, Angular `translate.use`), and `i18next.dir(resolvedLang)` direction — not the seed's B2E defaults.
+Follow the framework reference for the exact scaffold and never clobber existing wiring.
 
-**Pause:** "i18next setup [exists / created]. initI18n() is called at boot: [confirm]."
+**Pause:** "i18n setup [exists / created]. It's loaded at boot: [confirm]."
 
 ---
 
@@ -237,19 +255,18 @@ Act on the message `check-i18n-wired.sh` already printed (above): if it reports
 
 **Goal:** Guide the developer to verify labels render in a second language.
 
-**Action:** Follow the branch-specific procedure in [references/verifying.md](references/verifying.md).
+**Action:** Follow the branch-specific procedure in `references/common/verifying.md`.
 
-For **B2E**, activate a second language, author or retrieve its translation metadata, build against the target org, deploy only the target bundle and label metadata, then change the authenticated user's Language and reload. The exact commands and URLs are in [references/verifying.md](references/verifying.md).
+For **B2E**, activate a second language, author or retrieve its translation metadata, build against the target org, deploy only the target bundle and label metadata, then change the authenticated user's Language and reload.
 
-For **B2C**, verify configured site languages, URL routing, `SFDC_ENV.language`, the full-reload language switcher, localized local preview, guest GraphQL access, and cache clearing as detailed in [references/verifying.md](references/verifying.md).
+For **B2C**, verify configured site languages, URL routing, `SFDC_ENV.language`, the full-reload language switcher, localized local preview, guest GraphQL access, and cache clearing as detailed in the framework reference.
 
 Deploying the bundle, labels, and translations does not publish the Experience site. Treat `sf community publish` as a separate go-live mutation: show the exact site and target org, then wait for explicit user confirmation immediately before running it.
 
-**If it doesn't render:**
-Check the three gotchas in [references/gotchas.md](references/gotchas.md):
+**If it doesn't render:** check the gotchas in `references/common/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)
+- Stale label cache (React: `i18next_res_*` in localStorage; Angular: in-memory, reload refetches)
 - B2C guest GraphQL 403 (`GraphQLApiOrgPrefForGuestUsers` is not admin-enabled)
 - B2C route, site language, and `SFDC_ENV.language` disagree
 
@@ -262,7 +279,7 @@ Labels render in ≥2 locales, or the blocking gotcha is identified.
 
 ## 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.
+- **Already-localized code**: detect existing translation-call 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.
@@ -293,25 +310,25 @@ Labels render in ≥2 locales, or the blocking gotcha is identified.
             ├── i18n/
             │   ├── index.ts              ← init wiring (you write this once)
             │   └── label-manifest.ts     ← list of labels to fetch (you maintain this)
-            └── components/               ← components call t()
+            └── components/               ← components call the translation function
 ```
 
 | Command | Run from | Purpose |
 |---|---|---|
-| `npm install i18next react-i18next i18next-chained-backend i18next-localstorage-backend` | UI bundle dir | Install i18n dependencies (Step 4) |
+| Install i18n dependencies (see `references/<framework>/localize.md`) | UI bundle dir | Install the framework's i18n libraries (Step 4) |
 | `npm run build` | UI bundle dir | Build the app (API version bakes in, set target-org first) |
-| See `references/verifying.md` | Project root | Review and deploy the exact target bundle + changed label metadata to an explicit org |
+| See `references/<framework>/verifying.md` | Project root | Review and deploy the exact target bundle + changed label metadata to an explicit org |
 | `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
+- [ ] Every confirmed string has both a `CustomLabels` entry and a translation call
 - [ ] `label-manifest.ts` entry count == label count (no unregistered keys)
-- [ ] `initI18n()` present and called once at boot
+- [ ] i18n wiring present and called once at boot; manifest wired into the label backend/loader
 - [ ] B2C only: guest GraphQL preference confirmed, `USER_DEFAULT` configured, and site language route matches `SFDC_ENV.language`
-- [ ] B2E only: no `labelFallback` override; the `BASE_VALUE` default is preserved
+- [ ] B2E only: no fallback override; the framework reference's default is preserved
 - [ ] Labels render in ≥2 locales (or the blocking gotcha is named)
 - [ ] No hand-written machine translations landed in `*-meta.xml` (only scaffold-and-guide)
 - [ ] Both metadata files parse as XML; the translation scaffold has one `<Translations>` root and one closed block per label

package/skills/experience-ui-bundle-localize/references/angular/check-i18n-wired.sh

@@ -0,0 +1,159 @@
+#!/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 Angular ngx-translate wiring exists, is
+# registered with a custom loader, and is loaded at boot.
+#
+# Angular-specific: the detection targets are ngx-translate-shaped
+# (provideTranslateService / TranslateModule.forRoot, a TranslateLoader subclass,
+# and a boot-time TranslateService.use(...) call), which have no i18next analog,
+# so this script lives under the Angular reference (references/angular/) rather
+# than the shared scripts/ folder. The React equivalent (initI18n / SalesforceBackend
+# detection) lives under references/react/.
+#
+# 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 the
+# ngx-translate provider registration, a custom TranslateLoader class, and a
+# boot-time TranslateService.use(...) call.
+#
+# Usage (run from the UI bundle dir, or pass its src path):
+#   bash <skill-dir>/references/angular/check-i18n-wired.sh [src-dir]
+#
+# src-dir defaults to "src".
+#
+# When wiring exists, it also reports whether the label manifest is imported AND
+# actually referenced inside the loader class (not merely imported and left
+# unused), so the reconcile decision is a script result rather than a by-hand read.
+#
+# Exit codes (aligned with references/react/check-i18n-wired.sh and
+# scripts/check-manifest-registered.sh so the workflow branches on the code, not
+# the message text):
+#   0  fully wired — provideTranslateService / TranslateModule.forRoot registers
+#      the custom loader, a boot-time TranslateService.use(...) runs, AND the
+#      manifest is imported and referenced inside the loader. Just add new keys.
+#   1  no ngx-translate wiring found — neither a provider registration nor a
+#      TranslateLoader subclass. Scaffold the whole setup (see
+#      references/angular/i18n-setup.md).
+#   2  partially wired — a loader class OR a registration exists, but the setup is
+#      incomplete: the loader is not registered via provideTranslateService /
+#      TranslateModule.forRoot, or it is registered but nothing calls
+#      TranslateService.use(...) at boot. Add ONLY the missing wiring; do NOT
+#      re-scaffold or overwrite the existing loader.
+#   3  registered and booted, but the manifest could not be confirmed as reaching
+#      the loader (not imported into the loader file, no detectable loader class,
+#      or imported but never referenced in it). This is a textual heuristic: the
+#      manifest may be wired via a variable/factory/spread this check cannot see.
+#      VERIFY by hand; reconcile only if it genuinely dangles, and never clobber
+#      the existing loader.
+#  64  usage error — the source dir does not exist (bad argument or wrong cwd).
+#      This is NOT a "no wiring found" result; do not scaffold. Fix the path and
+#      re-run. (64 = EX_USAGE, kept out of the 0-3 semantic range so exit 1
+#      uniquely means "no wiring found".)
+# The message still names the specific file/symbol/gap for the report, but the
+# decision is the exit code.
+
+SRC_DIR="${1:-src}"
+if [ ! -d "$SRC_DIR" ]; then
+  echo "ERROR: source dir not found: $SRC_DIR (run from the UI bundle dir, or pass its src path)" >&2
+  exit 64
+fi
+
+# Use POSIX character classes, not \s / \b: BSD/macOS grep -E does not honor those.
+
+# (A) The ngx-translate provider registration: standalone provideTranslateService()
+#     or the NgModule TranslateModule.forRoot(). Either one means "the setup exists".
+REGISTERED=$(grep -rlE 'provideTranslateService[[:space:]]*\(|TranslateModule[[:space:]]*\.[[:space:]]*forRoot[[:space:]]*\(' \
+               "$SRC_DIR" --include='*.ts' 2>/dev/null | head -1 || true)
+
+# (B) A custom loader class: `... implements TranslateLoader` or `... extends <X>TranslateLoader`.
+#     -l over the whole tree; the file list is reused for the manifest-reach check.
+LOADER_FILES=$(grep -rlE '(implements|extends)[[:space:]].*TranslateLoader' \
+                 "$SRC_DIR" --include='*.ts' 2>/dev/null || true)
+LOADER=$(printf '%s' "$LOADER_FILES" | head -1 || true)
+
+# (C) A boot-time TranslateService.use(...) call: <translate-ish>.use( — matches
+#     translate.use(, this.translate.use(, translateService.use(, etc. This is the
+#     Angular analog of React's boot-time initI18n() call.
+BOOTED=$(grep -rlE '[Tt]ranslate[A-Za-z0-9_]*[[:space:]]*\.[[:space:]]*use[[:space:]]*\(' \
+           "$SRC_DIR" --include='*.ts' 2>/dev/null | head -1 || true)
+
+# --- Decision tree (mirrors the React script's DEFINES/CALLS/reconcile shape) ---
+
+# 1: nothing ngx-translate at all -> scaffold everything.
+if [ -z "$REGISTERED" ] && [ -z "$LOADER" ]; then
+  echo "no ngx-translate wiring found (no provideTranslateService/TranslateModule.forRoot and no TranslateLoader subclass under $SRC_DIR) -> scaffold it (see references/angular/i18n-setup.md)"
+  exit 1
+fi
+
+# 2a: a loader class exists but is never registered -> add only the provider wiring.
+if [ -z "$REGISTERED" ]; then
+  echo "TranslateLoader subclass defined in $LOADER but not registered (no provideTranslateService/TranslateModule.forRoot) -> add the provider registration; do not re-scaffold the loader"
+  exit 2
+fi
+
+# 2b: registered but nothing loads a language at boot -> add only the boot call.
+if [ -z "$BOOTED" ]; then
+  echo "ngx-translate registered in $REGISTERED but no boot-time TranslateService.use(...) call found -> add the boot wiring (fetch the i18n context and call translate.use(ctx.lang)); do not re-scaffold"
+  exit 2
+fi
+
+# Registered AND booted. Confirm the manifest actually reaches the loader: the
+# loader file must import the manifest AND reference the bound symbol somewhere
+# OTHER than its import line. Importing alone is not enough — a loader can
+# `import { labelManifest }` and never iterate it, in which case it fetches
+# nothing and every key renders as its own literal name. Resolve the symbol PER
+# loader file from that file's own import (named / aliased / default), because an
+# imported binding is only usable in the file that imports it.
+RESOLVE_SYMBOL='s/.*[{,][[:space:]]*labelManifest[[:space:]]+as[[:space:]]+([A-Za-z0-9_]+).*/\1/; t
+                s/.*[{,][[:space:]]*labelManifest[[:space:]]*[,}].*/labelManifest/; t
+                s/.*import[[:space:]]+labelManifest[[:space:]]+from.*/labelManifest/; t
+                s/.*/labelManifest/'
+
+MANIFEST_USED=""
+MANIFEST_SYMBOL="labelManifest"  # fallback for the message if no hit is found
+if [ -n "$LOADER_FILES" ]; then
+  while IFS= read -r LOADER_FILE; do
+    [ -z "$LOADER_FILE" ] && continue
+    FILE_IMPORT=$(grep -nE '^[[:space:]]*import[^A-Za-z0-9_].*(label-manifest|labelManifest)' \
+                    "$LOADER_FILE" 2>/dev/null | head -1 || true)
+    [ -z "$FILE_IMPORT" ] && continue   # this file cannot use a binding it never imported
+    SYM=$(printf '%s\n' "$FILE_IMPORT" | sed -E "$RESOLVE_SYMBOL")
+    [ -z "$SYM" ] && continue
+    # Reference to SYM anywhere OTHER than an import line (strip // comments and
+    # import lines first, so `import { labelManifest }` and a commented mention do
+    # not count as use). A bare `for (const e of labelManifest)` / `labelManifest.`
+    # / `[...labelManifest]` all match.
+    if sed -E 's://.*$::' "$LOADER_FILE" \
+         | grep -vE '^[[:space:]]*import[^A-Za-z0-9_]' \
+         | grep -qE "(^|[^A-Za-z0-9_])${SYM}([^A-Za-z0-9_]|$)" 2>/dev/null; then
+      MANIFEST_USED="yes"; MANIFEST_SYMBOL="$SYM"; break
+    fi
+  done <<EOF
+$LOADER_FILES
+EOF
+fi
+
+if [ -n "$MANIFEST_USED" ]; then
+  echo "i18n wired: ngx-translate registered in $REGISTERED, loaded at boot ($BOOTED), custom loader in $LOADER; the manifest ($MANIFEST_SYMBOL) is imported and referenced inside the loader -> add new keys to the manifest, do not clobber the loader"
+  exit 0
+fi
+
+# Registered + booted, but the manifest reach into the loader could not be
+# confirmed. Heuristic textual check, so treat exit 3 as "verify, do not clobber":
+# the manifest may be wired through a form this script cannot see (a factory, a
+# variable, a spread, or a loader class this check did not detect). Report the
+# specific gap for the human/agent to confirm before editing.
+MISSING=""
+if [ -z "$LOADER" ]; then
+  MISSING="no TranslateLoader subclass detected (the loader may use a factory/useFactory this check cannot see)"
+else
+  MANIFEST_IMPORT_ANY=$(grep -rhnE '^[[:space:]]*import[^A-Za-z0-9_].*(label-manifest|labelManifest)' \
+                          "$SRC_DIR" --include='*.ts' 2>/dev/null | head -1 || true)
+  if [ -z "$MANIFEST_IMPORT_ANY" ]; then
+    MISSING="the manifest is not imported into the loader file ($LOADER)"
+  else
+    MISSING="could not confirm the manifest is referenced inside the loader ($LOADER) (it may be imported but unused, or reached via a variable this check cannot see)"
+  fi
+fi
+echo "i18n wired: ngx-translate registered in $REGISTERED and loaded at boot ($BOOTED); but $MISSING -> verify by hand; if it genuinely dangles, reconcile (import the manifest AND iterate it in the loader's getTranslation) without clobbering"
+exit 3