@salesforce/afv-skills 1.41.0 → 1.43.0

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

@@ -1,6 +1,6 @@
 ---
 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."
+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."
 metadata:
   version: "1.0"
   domains: ["Experience"]
@@ -9,6 +9,7 @@ metadata:
     - "experience-ui-bundle-deploy"
     - "experience-ui-bundle-frontend-generate"
     - "experience-ui-bundle-salesforce-data-access"
+    - "experience-ui-bundle-site-generate"
   cliTools:
     - tool: ["jq"]
       semver: ">=1.6"
@@ -20,7 +21,7 @@ metadata:
 
 # 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.
+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.
 
 This file is the **workflow + guardrail spine**. Depth lives in linked docs:
 
@@ -51,6 +52,7 @@ 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** |
 
 ---
@@ -60,10 +62,11 @@ 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 | `@salesforce/platform-sdk` installed (≥11.42.1) | `package.json` in the UI bundle dir | Tell user to install it; cannot proceed |
+| 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 |
 | 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 |
+| 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) |
 
 **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:
 
@@ -73,21 +76,25 @@ 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:
+**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:
 
 ```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.
+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.
 
-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.
+For exit `10`, route by explicit request/context: if it says **B2C**, confirm precondition 6 and use the B2C branch; if it says **B2B**, reject it; if product type is not explicit, ask the user whether the site is B2C or B2B and stop until confirmed. For exits `12` and `13`, require the user to choose the runtime context (and site for exit `13`), then apply that branch's fallback and prerequisites. Never infer B2C from `DigitalExperienceConfig`, `appSpace`, `appContainer`, or `AUTHENTICATED_WITH_PUBLIC_ACCESS_ENABLED`; the authentication value means guest access is enabled.
+
+For B2C, only an org admin may enable `GraphQLApiOrgPrefForGuestUsers`; never provision or change it. Without it, guest label requests return HTTP 403. Track availability through W-23854208.
+
+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 add i18n wiring or TODO markers to a B2B or unknown bundle.
 
 ---
 
 ## Workflow: the five steps
 
-Each step has a **checkable completion criterion** and a **confirm-before-continue** pause.
+Each step has a **completion criterion** and a **confirm-before-continue** pause.
 
 ### Step 1: Detect
 
@@ -183,6 +190,8 @@ Branch on the exit code: `0`, every key is registered (or there are no `t()` cal
 
 **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"`. See [references/i18n-setup.md](references/i18n-setup.md) for both configurations and B2C language context.
+
 **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.
 
@@ -228,42 +237,21 @@ 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:**
-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>
-   ```
+**Action:** Follow the branch-specific procedure in [references/verifying.md](references/verifying.md).
 
-4. **Open the app** at the `/lwr/application/ai/<namespace>-<bundleName>` URL on the `lightning.force.com` domain (redirects to the app host).
+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).
 
-5. **Change the user's Language** (not Locale), Setup → My Settings → Language & Time Zone → Language → pick the translated language → Save.
+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).
 
-6. **Reload the app**, labels should flip to the translated language.
+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):
 - 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)
+- B2C guest GraphQL 403 (`GraphQLApiOrgPrefForGuestUsers` is not admin-enabled)
+- B2C route, site language, and `SFDC_ENV.language` disagree
 
 **Completion criterion:**
 Labels render in ≥2 locales, or the blocking gotcha is identified.
@@ -278,15 +266,17 @@ Labels render in ≥2 locales, or the blocking gotcha is identified.
 - **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.
+- **B2B site**: explicitly reject it. B2C support does not imply B2B support.
 
 ---
 
 ## 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.
+1. **Never machine-translate deployable metadata.** Scaffold one well-formed `<Translations>` document with a closed `<customLabels>` block per label and XML-escaped English source text. Preserve placeholders and parse both metadata files before completion. Translators replace scaffold values by hand or through Translation Workbench; never call an MT API for them.
 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.
+5. **Never publish a B2C site implicitly.** Metadata deployment and site publication are separate. Run `sf community publish` only after showing the site and org and receiving explicit confirmation for that publication.
 
 ---
 
@@ -310,7 +300,7 @@ Labels render in ≥2 locales, or the blocking gotcha is identified.
 |---|---|---|
 | `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 |
+| See `references/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 |
 
 ---
@@ -320,5 +310,8 @@ Labels render in ≥2 locales, or the blocking gotcha is identified.
 - [ ] 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
+- [ ] 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
 - [ ] 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/gotchas.md

@@ -81,7 +81,11 @@ If you built while pointed at a v65.0 org and deploy to a v63.0 org, the bundle
 ```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>
+sf project deploy start \
+  --source-dir force-app/main/default/uiBundles/<your-bundle> \
+  --source-dir force-app/main/default/labels/CustomLabels.labels-meta.xml \
+  --source-dir force-app/main/default/translations/<locale>.translation-meta.xml \
+  --target-org <same-alias>
 ```
 
 **Check an org's API version:**
@@ -190,7 +194,7 @@ English never needs activation.
 
 **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.
+**Cause (most likely):** The translation file is missing that label, or its `<name>` doesn't match the `<fullName>` in `CustomLabels`. The Platform SDK's GraphQL request returns a fallback according to `labelFallback` (`BASE_VALUE` for B2E, explicit `USER_DEFAULT` for B2C), so correct English text usually means that one key wasn't translated.
 
 **Other causes:**
 - The user's **Language** (not Locale) isn't set to the language you translated.
@@ -200,15 +204,25 @@ English never needs activation.
 
 ---
 
-### Logged-in user sees their own language instead of the org default
+### B2C guest labels request returns HTTP 403
 
-**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.
+**Symptom:** The B2C site loads, but a signed-out visitor's labels GraphQL request returns HTTP 403. The same request can work for an authenticated user.
 
-**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.
+**Cause:** `GraphQLApiOrgPrefForGuestUsers` is not enabled. Guest access to the GraphQL label path is an org-admin prerequisite tracked by W-23854208.
 
-**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.
+**Fix:** Ask an org admin to confirm and enable the preference through the supported administration process. This localization workflow must never provision or change it. Stop until the prerequisite is satisfied.
 
-> **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.
+### B2C language switch leaves old-language labels
+
+**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.
+
+**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.
+
+### 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.
 
 **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"`:
 
@@ -229,6 +243,8 @@ query Labels($ns: String!, $names: [String!]!, $locale: String, $fallback: Label
 
 with `"fallback": "BASE_VALUE"` in the variables.
 
+B2B remains unsupported. Do not infer B2B support from the B2C guidance or apply these steps to a B2B site.
+
 ---
 
 ### Large manifest: no per-query limit to manage yourself

package/skills/experience-ui-bundle-localize/references/i18n-setup.md

@@ -25,7 +25,7 @@ export async function initI18n() {
   const dataSDK = await createDataSDK();
   const ctx = await fetchI18nContext(dataSDK);
 
-  // Tell the browser the user's language + text direction (RTL support).
+  // B2E: the session language is the display language.
   document.documentElement.dir = ctx.dir;
   document.documentElement.lang = ctx.lang;
 
@@ -40,7 +40,7 @@ export async function initI18n() {
         backends: [LocalStorageBackend, SalesforceBackend],
         backendOptions: [
           { expirationTime: 86400000 }, // cache labels in localStorage for a day
-          { dataSDK, labelManifest }, // fetch the rest over GraphQL
+          { dataSDK, labelManifest }, // B2E: shipped BASE_VALUE fallback
         ],
       },
       interpolation: {
@@ -57,6 +57,34 @@ export async function initI18n() {
 }
 ```
 
+The example above is the **B2E** configuration. Do not set `labelFallback` for B2E: the shipped `SalesforceBackend` default is `BASE_VALUE`.
+
+For a **B2C** bundle, change only the Salesforce backend options entry:
+
+```typescript
+backendOptions: [
+  { expirationTime: 86400000 },
+  {
+    dataSDK,
+    labelManifest,
+    labelFallback: "USER_DEFAULT",
+  },
+],
+```
+
+`USER_DEFAULT` is required for B2C so fallback follows the guest/site language context. Do not copy this override into B2E wiring.
+
+For B2C, also set the document language and direction from the route-selected display language, not `ctx.dir`. The GraphQL i18n context direction reflects the guest session profile and can stay `ltr` after the site switches to an RTL language. Reuse the resolved language from the site's language-switcher integration:
+
+```typescript
+const resolvedLang =
+  (globalThis as { SFDC_ENV?: { language?: string } }).SFDC_ENV?.language || ctx.lang;
+document.documentElement.dir = i18next.dir(resolvedLang);
+document.documentElement.lang = resolvedLang.replace(/_/g, "-");
+```
+
+Before using this configuration, have an org admin confirm that `GraphQLApiOrgPrefForGuestUsers` is already enabled. This workflow must never enable it. Without the preference, unauthenticated GraphQL label requests return HTTP 403; see dependency W-23854208.
+
 **Call it once at boot**, before mounting your app:
 
 ```typescript
@@ -90,6 +118,22 @@ export const labelManifest = [
 
 The manifest is how i18next knows what to fetch. An **unregistered key fails silently**: it renders as its own literal name (e.g., `"Welcome_Text"` instead of "Welcome") with no console warning. Always keep the manifest in sync with your `t()` calls.
 
+## B2C language context
+
+A B2C site's configured languages and language-specific URLs are the source of truth. At boot, the site route supplies `SFDC_ENV.language`; the SDK detector uses that value to resolve labels. A language switcher must navigate to the target language URL and perform a full page reload. An in-place i18next language change is insufficient because the SDK context and localStorage-backed labels are established at boot.
+
+For local preview, use the site entry of the Vite plugin and pass the site's supported language codes, with the default first:
+
+```typescript
+import siteUiBundlePlugin from "@salesforce/vite-plugin-ui-bundle/site";
+
+export default defineConfig({
+  plugins: [siteUiBundlePlugin({ languages: ["en_US", "es", "ar"] })],
+});
+```
+
+The site plugin injects `SFDC_ENV.language` per request and serves non-default hyphenated language routes such as `/es` or `/en-US`; the default language has no prefix. Verify the injected language before judging label output. The authenticated org user's Language setting is not a substitute for the guest site's language context.
+
 ---
 
 ## Dependencies
@@ -100,7 +144,7 @@ Install these first (Step 4 of the main workflow):
 npm install i18next react-i18next i18next-chained-backend i18next-localstorage-backend
 ```
 
-Use `@salesforce/platform-sdk` **≥11.42.1**. The `@salesforce/platform-sdk/i18n` subpath (`SalesforceBackend`, `createSalesforceDetector`, `fetchI18nContext`) has existed since 11.4.1, and 11.7.0 added `reloadI18nContext` for refreshing the cached label context. 11.42.1 is the validated floor because it carries the fix that batches a namespace into 100-name-or-fewer queries. Without it, a manifest of more than 100 labels in one namespace hits the `uiapi.platform.labels` limit and the whole namespace read fails. Keep the SDK's siblings (`@salesforce/vite-plugin-ui-bundle`, `@salesforce/ui-bundle`) on the same version.
+Use aligned `@salesforce/platform-sdk`, `@salesforce/vite-plugin-ui-bundle`, and `@salesforce/ui-bundle` packages at **≥11.49.3**. Platform SDK 11.45.0 introduced the `labelFallback` option and shipped `BASE_VALUE` default, but the B2C local-preview entry `@salesforce/vite-plugin-ui-bundle/site` first appears in the 11.49.x line. Version 11.49.3 is therefore the common floor for this B2C-capable workflow. Earlier history: the i18n subpath existed in 11.4.1, 11.7.0 added `reloadI18nContext`, and 11.42.1 added namespace batching for the 100-name labels-query limit.
 
 Known-good companion versions:
 - `i18next` **^24.2.2**
@@ -125,7 +169,7 @@ If you see an older example that vendors `salesforce-detector.ts` or `salesforce
 
 1. Bundle loads, `initI18n()` runs
 2. `createDataSDK()` initializes the SDK
-3. `fetchI18nContext()` queries the org for the user's language/locale/direction
+3. `fetchI18nContext()` queries the org for language/locale/direction (B2C uses the site route's `SFDC_ENV.language`)
 4. `SalesforceBackend` reads the manifest and issues a GraphQL query per namespace:
    ```graphql
    query LoadLabels {

package/skills/experience-ui-bundle-localize/references/label-xml.md

@@ -77,6 +77,10 @@ One file per translated language (e.g., `es.translation-meta.xml` for Spanish, `
 </Translations>
 ```
 
+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.
+
 ### Fields
 
 | Field | Purpose | Notes |
@@ -105,7 +109,7 @@ You have two options:
 
 ### 1. Hand-edit the XML (for small apps)
 
-Create the `<locale>.translation-meta.xml` file, add one `<customLabels>` block per label, and type the translations directly. Good for a handful of labels or prototyping.
+Create the complete `<locale>.translation-meta.xml` document and add one complete `<customLabels>` block per label. For this skill's scaffold, keep the English source text rather than inventing translations; translators can replace it later. Good for a handful of labels or prototyping.
 
 ### 2. Use Translation Workbench (for scale)
 
@@ -233,14 +237,17 @@ To change a user's Language (to test translations), go to:
 </labels>
 ```
 
-### 2. Add the Spanish translation
+### 2. Add the untranslated Spanish scaffold
 
 `force-app/main/default/translations/es.translation-meta.xml`:
 ```xml
-<customLabels>
-  <label>Bienvenido</label>
-  <name>Welcome_Text</name>
-</customLabels>
+<?xml version="1.0" encoding="UTF-8"?>
+<Translations xmlns="http://soap.sforce.com/2006/04/metadata">
+  <customLabels>
+    <label>Welcome</label>
+    <name>Welcome_Text</name>
+  </customLabels>
+</Translations>
 ```
 
 ### 3. Register in the manifest
@@ -264,13 +271,20 @@ function WelcomeBanner() {
 ### 5. Deploy
 
 ```bash
-sf project deploy start --source-dir force-app --target-org <alias>
+sf project deploy start \
+  --source-dir force-app/main/default/uiBundles/<your-bundle> \
+  --source-dir force-app/main/default/labels/CustomLabels.labels-meta.xml \
+  --source-dir force-app/main/default/translations/<locale>.translation-meta.xml \
+  --target-org <alias>
 ```
 
+Review the exact paths and target org with the user before deploying. Repeat the translation path only for locale files changed by this task.
+
 ### 6. Verify
 
 - User with Language = English sees "Welcome"
-- User with Language = Spanish sees "Bienvenido"
+- Before translator review, a user with Language = Spanish also sees the scaffold value "Welcome"
+- After a translator replaces the scaffold value with `Bienvenido` and the metadata is retrieved/deployed, a user with Language = Spanish sees "Bienvenido"
 
 ---
 

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

@@ -6,13 +6,15 @@ How to build, deploy, open, and verify that labels render correctly in multiple
 
 ## Overview
 
-Verification has five steps:
+Authenticated B2E verification has five steps:
 1. **Build** the app (API version bakes in, point at the deploy target org first)
 2. **Deploy** the bundle + labels + translations in one shot
 3. **Open** the app at the correct URL (on the `lightning.force.com` domain)
 4. **Flip** the user's Language setting to the translated language
 5. **Reload** and confirm the labels render in the new language
 
+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.
+
 ---
 
 ## Step 1: Build the app
@@ -56,20 +58,24 @@ English (`en_US`) needs no activation; it's always available.
 
 ## Step 3: Deploy the bundle + labels + translations
 
-Deploy the entire `force-app` tree (bundle, labels, translations) in one command:
+Before deploying, inspect the local diff and construct exact source paths for the target bundle, `CustomLabels.labels-meta.xml`, and only the locale files changed by this task. Show the actual metadata diff/components, not only the filenames; if either shared label file contains unrelated changes, stop or get explicit approval for those changes too. Show the resolved target org (`sf org display --target-org <alias>`) and wait for explicit confirmation. Then deploy the approved paths, for example:
 
 ```bash
-sf project deploy start --source-dir force-app --target-org <your-org-alias>
+sf project deploy start \
+  --source-dir force-app/main/default/uiBundles/<your-bundle> \
+  --source-dir force-app/main/default/labels/CustomLabels.labels-meta.xml \
+  --source-dir force-app/main/default/translations/<locale>.translation-meta.xml \
+  --target-org <your-org-alias>
 ```
 
-**Run from the SFDX project root** (not from inside the bundle directory). `--source-dir force-app` deploys everything under that folder:
+**Run from the SFDX project root** (not from inside the bundle directory). The approved source paths deploy only:
 - `labels/CustomLabels.labels-meta.xml` (English base labels)
 - `translations/<locale>.translation-meta.xml` (translated labels)
 - `uiBundles/<your-bundle>/dist/` (the built app)
 
-You do **not** need a `package.xml` or any manifest entry; the CLI discovers the metadata automatically.
+You do **not** need a `package.xml` or any manifest entry; the CLI discovers the selected metadata automatically.
 
-**Point at `force-app`, not `uiBundles/`, or your labels and translations won't go up.**
+Repeat `--source-dir` for each approved locale file. Do not replace these paths with the broad `force-app`, `labels`, or `translations` directories unless the user explicitly intends to deploy every metadata change in them.
 
 ---
 
@@ -115,6 +121,22 @@ To test translations, you need to change the **Language** setting (not Locale, s
 
 **Reload the app.** Labels should now render in the selected language.
 
+This step is for **B2E only**. For B2C, use the site language route below.
+
+---
+
+## B2C: verify a guest site language
+
+1. In the site administration experience, configure at least two supported languages. Translation Workbench activation and translation metadata remain required, but they do not by themselves add a language to the site.
+2. Confirm an org admin has already enabled `GraphQLApiOrgPrefForGuestUsers` (W-23854208). Never enable it as part of this workflow. Without it, a guest's GraphQL label request returns HTTP 403.
+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.
+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.
+
 ---
 
 ## Language vs Locale (common confusion)
@@ -140,7 +162,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 key is in the manifest but untranslated for the active language, i18next renders the **English base value** (via `fallbackLng: "en"` in the init). That's correct behavior; it just means that one key wasn't translated yet.
+**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.
 
 ---
 
@@ -178,11 +200,11 @@ 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.**
 
-Asked with `fallback: BASE_VALUE`, the GraphQL server returns the label's base value for a regional Language it has no explicit translation for: `resolvedLocale` comes back as the base (`en_US`) with `wasFallback: true`. The server does **not** map `en_GB → en_US` region-aware; it just honors the base-value fallback. On the documented SDK floor (11.42.1) the backend does not yet request `BASE_VALUE`, so it resolves with the server default (`USER_DEFAULT`): a guest or org-default user still lands on the base value, but see the related note below for the logged-in case. The base-value request ships in a later SDK release (see [gotchas.md](gotchas.md)).
+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.
 
 **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.
 
-**Related:** if instead a *logged-in* user sees **their own** language (not the org default) for an untranslated label, that's the fallback-strategy case, see [gotchas.md](gotchas.md) ("Logged-in user sees their own language instead of the org default"). On 11.42.1 that is the expected behavior, since the backend still uses `USER_DEFAULT`; author an explicit org-default translation to avoid it. The `BASE_VALUE` fallback that prevents it arrives in a later SDK release.
+For B2C, the skill explicitly configures `labelFallback: "USER_DEFAULT"`; test fallback through the guest site's configured language URL rather than by changing an authenticated user's Language.
 
 ---
 
@@ -192,11 +214,16 @@ Use this to confirm everything works:
 
 - [ ] Built against the correct org (API version matches deploy target)
 - [ ] Every translated language is activated in the org
-- [ ] Deployed `force-app` (bundle + labels + translations in one shot)
+- [ ] Deployed only the target bundle + labels + translations directories
 - [ ] 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
+- [ ] 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)
+- [ ] B2C: language switcher performs a full reload and localized local preview was checked
+- [ ] B2B was excluded; this workflow does not support B2B sites
 
 ---
 
@@ -206,7 +233,8 @@ Use this to confirm everything works:
 |---|---|---|
 | `sf config set target-org=<alias>` | Anywhere | Set default org (API version bakes in on next build) |
 | `npm run build` | UI bundle dir | Build the app |
-| `sf project deploy start --source-dir force-app --target-org <alias>` | Project root | Deploy bundle + labels + translations |
+| `sf project deploy start --source-dir force-app/main/default/uiBundles/<bundle> --source-dir force-app/main/default/labels/CustomLabels.labels-meta.xml --source-dir force-app/main/default/translations/<locale>.translation-meta.xml --target-org <alias>` | Project root | Deploy the approved target bundle + exact label metadata paths |
+| `sf community publish --name "<network-name>" --target-org <alias>` | Project root | Publish the B2C site, only after resolving `Network.Name` and separate explicit confirmation |
 | `sf project retrieve start --metadata Translations:<locale>` | Project root | Pull translations authored in Translation Workbench |
 
 ---