/experience-ui-bundle-localize

name: experience-ui-bundle-localize
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.2"
  domains: ["Experience"]
  minApiVersion: "68.0"
  relatedSkills:
    - "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"
    - tool: ["npm"]
      semver: ">=7.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

Localize a UI Bundle

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 **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 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.

---

Step 0: Route the task

| The task is… | Go to | |---|---| | Bundle doesn't exist yet | **experience-ui-bundle-frontend-generate** skill | | Deploying the app with its labels | **experience-ui-bundle-deploy** skill | | Configuring site languages or `sfdc_cms__languageSettings` | **experience-ui-bundle-site-generate** skill | | 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 "<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).

---

Preconditions: verify before editing

| # | Requirement | Verify | If missing | |---|---|---|---| | 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 | T