@salesforce/afv-skills 1.50.0 → 1.52.0

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

@@ -0,0 +1,250 @@
+# i18n Setup: the two files you write (Angular / ngx-translate)
+
+You write two files to set up i18n in an Angular UI Bundle: a **custom `TranslateLoader`** that
+fetches Custom Labels over GraphQL, and the **label manifest**. The Platform SDK provides the
+runtime plumbing (context fetch, the GraphQL surface); ngx-translate provides the pipe/service.
+The shared engine — the Labels query, manifest format, batching, and fallback — is documented
+once in [`../common/platform-sdk-i18n.md`](../common/platform-sdk-i18n.md); this file only covers
+the Angular wiring.
+
+> **Why a custom loader?** React drops the shipped `SalesforceBackend` straight into i18next.
+> ngx-translate loads translations through a `TranslateLoader` instead, so you implement one
+> that issues the **same** `uiapi.platform.labels` query. `SalesforceBackend` is i18next-shaped
+> (it implements i18next's `read()` contract), so it isn't reused directly here.
+
+---
+
+## File 1: `src/i18n/salesforce-translate-loader.ts` (the label loader)
+
+This is the only "glue" you write. `getTranslation(lang)` returns an `Observable` of a flat
+`{ key: value }` map for that language — exactly what ngx-translate expects.
+
+```typescript
+import { Injectable } from "@angular/core";
+import type { TranslateLoader } from "@ngx-translate/core";
+import { createDataSDK } from "@salesforce/platform-sdk";
+import { from, Observable } from "rxjs";
+import { labelManifest } from "./label-manifest";
+
+const LABELS_QUERY = `
+  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
+        }
+      }
+    }
+  }`;
+
+const MAX_NAMES_PER_QUERY = 100; // uiapi.platform.labels rejects > 100 names per call
+// B2E: keep "BASE_VALUE" (the shipped default). B2C: use "USER_DEFAULT" (see below).
+const LABEL_FALLBACK = "BASE_VALUE";
+
+@Injectable({ providedIn: "root" })
+export class SalesforceTranslateLoader implements TranslateLoader {
+  getTranslation(lang: string): Observable<Record<string, string>> {
+    return from(this.loadLabels(lang));
+  }
+
+  private async loadLabels(lang: string): Promise<Record<string, string>> {
+    const dataSDK = await createDataSDK();
+    if (!dataSDK.graphql) throw new Error("Data SDK GraphQL surface unavailable");
+    // Hoist to a local const: TypeScript drops the `!dataSDK.graphql` narrowing inside the
+    // async batch closures below, so referencing `dataSDK.graphql.query` there re-widens to
+    // possibly-undefined (TS18048). The local const keeps the narrowed type.
+    const graphql = dataSDK.graphql;
+
+    // Group "namespace:Key" manifest entries by namespace.
+    const byNamespace = new Map<string, string[]>();
+    for (const entry of labelManifest) {
+      const idx = entry.indexOf(":");
+      const ns = idx === -1 ? "c" : entry.slice(0, idx);
+      const name = idx === -1 ? entry : entry.slice(idx + 1);
+      (byNamespace.get(ns) ?? byNamespace.set(ns, []).get(ns)!).push(name);
+    }
+
+    const result: Record<string, string> = {};
+    // Fetch each namespace, chunked into <=100-name batches, all in parallel.
+    await Promise.all(
+      [...byNamespace].flatMap(([ns, names]) => {
+        const unique = [...new Set(names)];
+        const batches: string[][] = [];
+        for (let i = 0; i < unique.length; i += MAX_NAMES_PER_QUERY) {
+          batches.push(unique.slice(i, i + MAX_NAMES_PER_QUERY));
+        }
+        return batches.map(async (batch) => {
+          const res = await graphql.query<any>({
+            operationName: "Labels",
+            query: LABELS_QUERY,
+            variables: { ns, names: batch, locale: lang, fallback: LABEL_FALLBACK },
+          });
+          const labels = res?.data?.uiapi?.platform?.labels ?? [];
+          for (const label of labels) {
+            if (label?.value != null) {
+              // Default "c" labels use the bare key; other namespaces keep the prefix.
+              const key = ns === "c" ? label.name : `${ns}:${label.name}`;
+              result[key] = label.value;
+            }
+          }
+        });
+      }),
+    );
+    return result;
+  }
+}
+```
+
+Notes:
+- `dataSDK.graphql.query` **never rejects** — transport/GraphQL errors arrive on `res.errors`.
+  Inspect it if you want to surface a hard failure; the example simply treats missing data as
+  "no labels for this batch."
+- ngx-translate has a single flat key space per language (no namespace concept). Default `c`
+  labels are keyed by bare name (`{{ 'Welcome_Text' | translate }}`); non-`c` namespaces keep
+  their prefix (`{{ 'LightningDatatable:sort' | translate }}`). Most bundles use only `c`.
+- `createDataSDK()` is called here per language load. To avoid re-initializing it, wrap it in a
+  root-provided service and inject that into the loader and the boot initializer below.
+
+### B2C variant
+
+For a **B2C** bundle, set the fallback to follow the guest/site language context:
+
+```typescript
+const LABEL_FALLBACK = "USER_DEFAULT"; // B2C only — do NOT use for B2E
+```
+
+Before using B2C wiring, have an org admin confirm `GraphQLApiOrgPrefForGuestUsers` is already
+enabled. This workflow must never enable it. Without the preference, unauthenticated GraphQL
+label requests return HTTP 403 (dependency W-23854208).
+
+---
+
+## File 2: `src/i18n/label-manifest.ts` (the list of labels your app uses)
+
+Identical format to every framework — a flat `"namespace:Key"` array (see
+[`../common/platform-sdk-i18n.md`](../common/platform-sdk-i18n.md) and
+[`../common/label-xml.md`](../common/label-xml.md)):
+
+```typescript
+export const labelManifest = [
+  "c:Welcome_Text",
+  "c:Save_Button",
+  "c:Save_Failed_Message",
+  // one entry per label, "namespace:Key"
+];
+```
+
+An **unregistered key fails silently**: it renders as its own literal name (e.g. `"Welcome_Text"`
+instead of "Welcome") with no console warning. Keep the manifest in sync with your `translate`
+call sites — `check-manifest-registered.sh --framework angular` verifies this.
+
+---
+
+## Wiring: `src/app/app.config.ts`
+
+Register ngx-translate with the custom loader in the standalone providers, and set the app's
+`{0}/{1}` interpolation parser (see [interpolation.md](./interpolation.md)):
+
+```typescript
+import { ApplicationConfig, provideAppInitializer, inject } from "@angular/core";
+import {
+  provideTranslateService,
+  TranslateLoader,
+  TranslateService,
+} from "@ngx-translate/core";
+import { createDataSDK } from "@salesforce/platform-sdk";
+import { fetchI18nContext } from "@salesforce/platform-sdk/i18n";
+import { firstValueFrom } from "rxjs";
+import { SalesforceTranslateLoader } from "../i18n/salesforce-translate-loader";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // …your existing providers (provideRouter(routes), etc.)
+    provideTranslateService({
+      loader: { provide: TranslateLoader, useClass: SalesforceTranslateLoader },
+      // Fallback language when a key isn't loaded for the active language.
+      // v16+ renamed this option `defaultLanguage` → `fallbackLang`; older majors use
+      // `defaultLanguage`. Match your installed @ngx-translate/core.
+      fallbackLang: "en",
+      // parser: { provide: TranslateParser, useClass: PositionalParser }, // see interpolation.md
+    }),
+
+    // Boot: read the org locale context, set <html> dir/lang, load the active language,
+    // and block bootstrap until labels are ready.
+    provideAppInitializer(async () => {
+      const translate = inject(TranslateService);
+      const dataSDK = await createDataSDK();
+      const ctx = await fetchI18nContext(dataSDK);
+
+      // B2E: the session language is the display language.
+      document.documentElement.dir = ctx.dir;
+      document.documentElement.lang = ctx.lang;
+
+      await firstValueFrom(translate.use(ctx.lang)); // triggers the loader for that language
+    }),
+  ],
+};
+```
+
+`main.ts` stays as generated (`bootstrapApplication(App, appConfig)`); the app initializer runs
+and resolves before the root component renders, so labels are present on first paint.
+
+### B2C: display language from the site route
+
+For B2C, drive the document language 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:
+
+```typescript
+const resolvedLang =
+  (globalThis as { SFDC_ENV?: { language?: string } }).SFDC_ENV?.language || ctx.lang;
+document.documentElement.lang = resolvedLang.replace(/_/g, "-");
+await firstValueFrom(translate.use(resolvedLang));
+```
+
+A B2C language switcher must **navigate to the target language URL and perform a full page
+reload** — changing `translate.use(...)` in place leaves the boot-time SDK context and cached
+labels stale. Confirm the route and `SFDC_ENV.language` agree.
+
+---
+
+## Dependencies
+
+Install ngx-translate (Step 4 of the main workflow), choosing a `@ngx-translate/core` release
+compatible with the bundle's Angular version (the standalone `provideTranslateService` API is
+v16+; Angular 21 bundles use the current major):
+
+```bash
+npm install @ngx-translate/core
+```
+
+Keep the `@salesforce/platform-sdk`, `@salesforce/ui-bundle`, and Angular build-plugin siblings
+aligned at **≥11.49.3** (see [`../common/platform-sdk-i18n.md`](../common/platform-sdk-i18n.md)
+for the version-floor rationale).
+
+---
+
+## What you DON'T write
+
+The Platform SDK ships the runtime engine — you do **not** re-implement locale detection or the
+context fetch:
+- `fetchI18nContext` / `reloadI18nContext`: language, locale, direction, currency, time zone
+- `createDataSDK`: the GraphQL surface your loader queries
+- `createI18nFormatters`: Intl date/number/currency formatters
+
+You **do** write the `TranslateLoader` (the Angular analog of React's `SalesforceBackend`),
+because ngx-translate loads through that contract. See
+[`../common/platform-sdk-i18n.md`](../common/platform-sdk-i18n.md) for the query it issues.
+
+---
+
+## Related
+
+- [../common/platform-sdk-i18n.md](../common/platform-sdk-i18n.md): the shared runtime engine
+- [../common/label-xml.md](../common/label-xml.md): the Custom Labels metadata XML shape
+- [interpolation.md](./interpolation.md): how `{0}/{1}` placeholders work with ngx-translate
+- [../common/verifying.md](../common/verifying.md): the serve/verify flow
+- [../common/gotchas.md](../common/gotchas.md): silent-fail traps to avoid

package/skills/experience-ui-bundle-localize/references/angular/interpolation.md

@@ -0,0 +1,156 @@
+# Interpolation: `{0}`, `{1}` placeholders with ngx-translate
+
+Salesforce Custom Labels use **positional interpolation**: `{0}`, `{1}`, `{N}` placeholders that
+get replaced with runtime values. This is the same syntax used by Apex `String.format`, LWC
+`@salesforce/label`, and the React path — so one label works across all of them. The
+placeholder convention itself is framework-neutral (see
+[`../common/label-xml.md`](../common/label-xml.md)); this file covers the **Angular render**.
+
+---
+
+## The gotcha: ngx-translate defaults to `{{param}}`, not `{0}`
+
+Out of the box, ngx-translate interpolates **named** placeholders in double braces
+(`{{name}}`). Salesforce labels use **positional single-brace** placeholders (`{0}`). To bridge
+them, register a small custom `TranslateParser` that substitutes `{0}`, `{1}`, … This is the
+Angular analog of React's i18next `interpolation: { prefix: "{", suffix: "}" }` config.
+
+### `src/i18n/positional-translate-parser.ts`
+
+```typescript
+import { Injectable } from "@angular/core";
+import { TranslateDefaultParser } from "@ngx-translate/core";
+
+@Injectable()
+export class PositionalTranslateParser extends TranslateDefaultParser {
+  override interpolate(
+    expr: string | ((...args: unknown[]) => string),
+    params?: Record<string, unknown>,
+  ): string | undefined {
+    if (typeof expr !== "string") return super.interpolate(expr, params);
+    if (!params) return expr;
+    // Replace {0}, {1}, … with params["0"], params["1"], …; leave unmatched ones as-is.
+    return expr.replace(/\{(\d+)\}/g, (match, index) =>
+      params[index] != null ? String(params[index]) : match,
+    );
+  }
+}
+```
+
+Register it in `provideTranslateService(...)` (see [i18n-setup.md](./i18n-setup.md)):
+
+```typescript
+import { TranslateParser } from "@ngx-translate/core";
+
+provideTranslateService({
+  loader: { provide: TranslateLoader, useClass: SalesforceTranslateLoader },
+  parser: { provide: TranslateParser, useClass: PositionalTranslateParser },
+  defaultLanguage: "en",
+});
+```
+
+---
+
+## Passing values
+
+Params are an object keyed by the **placeholder number as a string** (`"0"`, `"1"`). A plain
+`{ 0: … }` literal works — JS object keys are strings.
+
+```html
+<!-- Label: "Hello, {0}" -->
+<h1>{{ 'Greeting' | translate:{ '0': userName } }}</h1>
+<!-- → "Hello, Tosin" -->
+
+<!-- Label: "Failed to save {0}: {1}" -->
+<p>{{ 'Save_Failed' | translate:{ '0': objectName, '1': reason } }}</p>
+```
+
+```typescript
+// imperative form
+this.translate.instant("Save_Failed", { 0: "Account", 1: "Permission denied" });
+// → "Failed to save Account: Permission denied"
+
+this.translate.get("Record_Count", { 0: 42, 1: 100 }).subscribe(/* … */);
+// label "Showing {0} of {1} records" → "Showing 42 of 100 records"
+```
+
+Order in the object doesn't matter; the placeholder **number** binds. The same placeholder can
+appear more than once (`"User {0} cannot edit {0}'s own profile"`) — every `{0}` is replaced.
+
+---
+
+## Translations must preserve placeholders
+
+The placeholders stay as `{0}`, `{1}` in every translation; they can move (grammar may reorder
+them) but the **numbers must match**:
+
+```xml
+<!-- English -->  <value>Failed to save {0}: {1}</value>
+<!-- Spanish -->  <label>Error al guardar {0}: {1}</label>
+```
+
+---
+
+## Numeric / date values are not locale-formatted
+
+Interpolation is a string replace — `{ 0: 1234.5 }` renders JS's default `toString`, not
+`1.234,5`. For locale-aware output, format first and pass the **formatted string**:
+
+```typescript
+const formatted = new Intl.NumberFormat(ctx.locale).format(count);
+this.translate.instant("Record_Count", { 0: formatted, 1: total });
+```
+
+The Platform SDK's `createI18nFormatters(ctx)` gives you `formatDate` / `formatNumber` /
+`formatCurrency` bound to `ctx.locale` (see [`../common/platform-sdk-i18n.md`](../common/platform-sdk-i18n.md)).
+
+---
+
+## Failure modes
+
+- **Missing placeholder value** — `instant("Greeting", { 0: "Tosin" })` on label
+  `"Hello, {0} from {1}"` renders `"Hello, Tosin from {1}"` (the unmatched placeholder leaks).
+  No error; always pass every placeholder the label expects.
+- **Missing label entirely** — `instant("Nonexistent_Key")` renders the literal key string.
+  That's the **unregistered manifest key** trap (see [`../common/gotchas.md`](../common/gotchas.md)):
+  the label was never fetched, so there's nothing to interpolate.
+
+---
+
+## Pluralization
+
+Unlike i18next, ngx-translate has **no built-in plural suffixing**. Two options:
+
+1. **Separate labels + manual selection** (portable, matches the React label set): author
+   `Item_Count_one` / `Item_Count_other`, register both, and pick the key in code from
+   `new Intl.PluralRules(ctx.lang).select(count)`:
+   ```typescript
+   const form = new Intl.PluralRules(ctx.lang).select(count); // "one" | "other" | …
+   this.translate.instant(`Item_Count_${form}`, { 0: count });
+   ```
+2. **ICU MessageFormat** via `@ngx-translate/message-format-compiler` — install it and register
+   its compiler in `provideTranslateService({ compiler: … })` if you want ICU `{count, plural, …}`
+   syntax inside label values. This changes the label authoring format, so coordinate with the
+   translation team.
+
+Languages with more plural forms (Russian, Polish, Arabic) need the extra label variants
+(`_zero`, `_few`, `_many`).
+
+---
+
+## Why positional (`{0}`) instead of named?
+
+**Portability.** The same Custom Label metadata is consumed by Apex (`String.format`), LWC
+(`@salesforce/label` with `{0}/{1}`), and both UI Bundle frameworks. Positional placeholders let
+one authored/translated string serve all of them; a named format would fork the label per
+framework and per translator. The custom parser above is what lets Angular join that convention.
+
+---
+
+## Related
+
+- [../common/label-xml.md](../common/label-xml.md): authoring labels with placeholders
+- [i18n-setup.md](./i18n-setup.md): where the parser is registered
+- [../common/platform-sdk-i18n.md](../common/platform-sdk-i18n.md): the shared runtime engine
+- [../common/verifying.md](../common/verifying.md): testing interpolated labels
+- [../common/gotchas.md](../common/gotchas.md): silent-fail traps

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

@@ -0,0 +1,111 @@
+# Angular reference — Localize an Angular UI Bundle
+
+Framework-specific companion to `SKILL.md` for the **Angular** path. `SKILL.md` owns the
+neutral workflow + guardrail spine (Step 0 routing, preconditions, the five steps, and the
+guardrails); this file owns everything Angular/ngx-translate-specific: the runtime library, the
+call convention, the wiring shape, and the framework depth doc. The shared engine and the
+framework-neutral depth docs live in [`../common/`](../common/).
+
+## Library & call convention
+
+An Angular 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 Angular bundle doesn't go
+through. Instead the app **fetches labels at runtime** through the Salesforce GraphQL UI API and
+hands them to **[ngx-translate](https://ngx-translate.org/)** (`@ngx-translate/core`) to render.
+
+The engine that does the fetching is the same one React uses — see
+[`../common/platform-sdk-i18n.md`](../common/platform-sdk-i18n.md). What's Angular-specific is
+that ngx-translate loads translations through a **`TranslateLoader`**, so instead of React's
+shipped `SalesforceBackend` you write a small custom loader that issues the same
+`uiapi.platform.labels` GraphQL query.
+
+```html
+<!-- template: pipe form (most common) -->
+<h1>{{ 'Welcome_Text' | translate }}</h1>
+
+<!-- template: directive form -->
+<h1 [translate]="'Welcome_Text'"></h1>
+```
+
+```typescript
+// component/service: imperative form
+constructor(private translate: TranslateService) {}
+label = this.translate.instant("Welcome_Text");   // sync (translations already loaded)
+this.translate.get("Welcome_Text").subscribe(v => …);  // async Observable
+```
+
+- **Call sites:** the `translate` pipe / directive in templates, and
+  `TranslateService.instant / get / stream("Key")` in code. The key is the bare `<fullName>`
+  (the `c` namespace is the default).
+- **Files scanned for user-facing strings / call sites:** `.html` (templates) and `.ts`
+  (inline templates + service calls).
+- **To use `t`-style translation in a component:** import ngx-translate's `TranslatePipe` (and/or
+  `TranslateDirective`) into the standalone component's `imports`, and/or inject
+  `TranslateService`.
+
+## Step 2 (Extract) — Angular specifics
+
+Replace the template literal with the `translate` pipe and import `TranslatePipe` into the
+component's `imports` array:
+
+```html
+<!-- Before: <h1>Welcome</h1> -->
+<!-- After:  <h1>{{ 'Welcome_Text' | translate }}</h1> -->
+```
+
+```typescript
+import { TranslatePipe } from "@ngx-translate/core";
+
+@Component({
+  selector: "app-welcome",
+  standalone: true,
+  imports: [TranslatePipe],   // ← add
+  templateUrl: "./welcome.html",
+})
+export class Welcome {}
+```
+
+For strings built in TypeScript (dynamic messages, `aria-label` bindings), inject
+`TranslateService` and call `instant(...)` / `get(...)`.
+
+## Step 4 (Wire) — Angular specifics
+
+Install ngx-translate (tell the user to run, from the UI bundle dir — pick a `@ngx-translate/core`
+release compatible with the bundle's Angular version; the standalone `provideTranslateService`
+API is v16+):
+
+```bash
+npm install @ngx-translate/core
+```
+
+Then scaffold the two files — the custom `SalesforceTranslateLoader` (`src/i18n/salesforce-translate-loader.ts`)
+and the label manifest (`src/i18n/label-manifest.ts`) — register the loader via
+`provideTranslateService(...)` in `src/app/app.config.ts`, and at boot fetch the i18n context and
+call `TranslateService.use(lang)` before the app renders. Full loader code and the B2E vs B2C
+configuration are in [i18n-setup.md](./i18n-setup.md).
+
+## Scripts
+
+Run them from the UI bundle dir (they scan `src/` relative to the current directory). The first
+three are framework-neutral and live in the skill's shared `scripts/` folder; `check-i18n-wired.sh`
+is Angular-specific (ngx-translate `provideTranslateService` / `TranslateLoader` detection) and
+ships here in the Angular reference folder.
+
+| Script | Purpose |
+|--------|---------|
+| [`check-org-api-version.sh`](../../scripts/check-org-api-version.sh) | Precondition 4 — org supports API v68.0+ |
+| [`detect-bundle-type.sh`](../../scripts/detect-bundle-type.sh) | Precondition 5 — classify B2E / B2C / internal |
+| [`check-manifest-registered.sh --framework angular`](../../scripts/check-manifest-registered.sh) | Step 3 — every `translate` key is registered in the manifest (`--framework angular` selects the `.html` pipe/directive + `.ts` service-call grammar) |
+| [`check-i18n-wired.sh`](./check-i18n-wired.sh) | Step 4 — the loader + `provideTranslateService` are wired, called at boot, and the manifest reaches the loader |
+
+## Depth docs
+
+Framework-neutral (shared with React), in [`../common/`](../common/):
+- [platform-sdk-i18n.md](../common/platform-sdk-i18n.md) — the shared runtime engine: the Labels GraphQL query, `fetchI18nContext`, the manifest format, batching, and fallback
+- [label-xml.md](../common/label-xml.md) — Custom Labels and translation metadata XML shapes; the `namespace:Key` rules
+- [verifying.md](../common/verifying.md) — serve URL, locale flip, and verifying labels render
+- [gotchas.md](../common/gotchas.md) — the silent-fail traps: unregistered manifest keys, API-version bake-in, stale label cache
+
+Angular-specific (this folder):
+- [i18n-setup.md](./i18n-setup.md) — the two files you write: the custom `TranslateLoader` + the label manifest
+- [interpolation.md](./interpolation.md) — positional `{0}/{1}` placeholder interpolation with ngx-translate