@salesforce/afv-skills 1.34.0 → 1.35.0

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

@@ -0,0 +1,169 @@
+# i18n Setup: the two files you write
+
+You write two files to set up i18n in a React UI Bundle. The Platform SDK provides the runtime plumbing (detector, backend, context fetch); you just wire it into i18next.
+
+---
+
+## File 1: `src/i18n/index.ts` (the init wiring)
+
+This is the only "glue" you write. It connects the SDK's i18n pieces to i18next.
+
+```typescript
+import { createDataSDK } from "@salesforce/platform-sdk";
+import {
+  createSalesforceDetector,
+  fetchI18nContext,
+  SalesforceBackend,
+} from "@salesforce/platform-sdk/i18n";
+import i18next from "i18next";
+import ChainedBackend from "i18next-chained-backend";
+import LocalStorageBackend from "i18next-localstorage-backend";
+import { initReactI18next } from "react-i18next";
+import { labelManifest } from "./label-manifest";
+
+export async function initI18n() {
+  const dataSDK = await createDataSDK();
+  const ctx = await fetchI18nContext(dataSDK);
+
+  // Tell the browser the user's language + text direction (RTL support).
+  document.documentElement.dir = ctx.dir;
+  document.documentElement.lang = ctx.lang;
+
+  await i18next
+    .use(ChainedBackend)
+    .use(createSalesforceDetector(dataSDK))
+    .use(initReactI18next)
+    .init({
+      fallbackLng: "en", // untranslated keys fall back to the English base value
+      defaultNS: "c", // "c" = your org's custom-label namespace
+      backend: {
+        backends: [LocalStorageBackend, SalesforceBackend],
+        backendOptions: [
+          { expirationTime: 86400000 }, // cache labels in localStorage for a day
+          { dataSDK, labelManifest }, // fetch the rest over GraphQL
+        ],
+      },
+      interpolation: {
+        // escapeValue: false is correct for React: React already escapes JSX
+        // output. Do NOT feed interpolated label output into
+        // dangerouslySetInnerHTML; that bypasses React's escaping and, with this
+        // setting, is an XSS vector when a label interpolates user-controlled
+        // text. Render labels as normal JSX (`{t(...)}`).
+        escapeValue: false,
+        prefix: "{", // Salesforce labels interpolate with {0}, {1}, …
+        suffix: "}",
+      },
+    });
+}
+```
+
+**Call it once at boot**, before mounting your app:
+
+```typescript
+// src/index.tsx
+import { initI18n } from "./i18n";
+
+initI18n().then(() => {
+  // mount app here
+  root.render(<App />);
+});
+```
+
+---
+
+## File 2: `src/i18n/label-manifest.ts` (the list of labels your app uses)
+
+This tells i18next which labels to fetch at boot.
+
+```typescript
+export const labelManifest = [
+  "c:Welcome_Text",
+  "c:Save_Button",
+  "c:Save_Failed_Message",
+  // one entry per label, "namespace:Key"
+];
+```
+
+**Format:** `"<namespace>:<Key>"`
+- `c` = custom labels in your org
+- `Key` = the `<fullName>` from your `CustomLabels.labels-meta.xml`
+
+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.
+
+---
+
+## Dependencies
+
+Install these first (Step 4 of the main workflow):
+
+```bash
+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.
+
+Known-good companion versions:
+- `i18next` **^24.2.2**
+- `react-i18next` **^15.5.1**
+- `i18next-chained-backend` **^4.6.2**
+- `i18next-localstorage-backend` **^4.2.0**
+
+---
+
+## What you DON'T write
+
+The Platform SDK ships with:
+- `createSalesforceDetector`: reads the user's language from the org
+- `SalesforceBackend`: fetches labels over GraphQL
+- `fetchI18nContext`: gets language, locale, text direction, currency
+
+If you see an older example that vendors `salesforce-detector.ts` or `salesforce-backend.ts` into `src/`, it predates the SDK's i18n export. You no longer copy those files in; just import from `@salesforce/platform-sdk/i18n`.
+
+---
+
+## How it works at boot
+
+1. Bundle loads, `initI18n()` runs
+2. `createDataSDK()` initializes the SDK
+3. `fetchI18nContext()` queries the org for the user's language/locale/direction
+4. `SalesforceBackend` reads the manifest and issues a GraphQL query per namespace:
+   ```graphql
+   query LoadLabels {
+     uiapi {
+       platform {
+         labels(namespace: "c", names: ["Welcome_Text", "Save_Button", ...]) {
+           name
+           value
+           resolvedLocale
+         }
+       }
+     }
+   }
+   ```
+5. Platform returns labels at the user's resolved locale
+6. i18next caches them (in memory + localStorage)
+7. React mounts; components call `t()`; lookups hit the cache
+
+The two backends chain: `LocalStorageBackend` serves cached labels (24-hour expiry), and `SalesforceBackend` fetches misses over GraphQL. This makes subsequent loads fast.
+
+---
+
+## Namespace note
+
+`defaultNS: "c"` means components can call `t("Welcome_Text")` instead of `t("c:Welcome_Text")`; the namespace is implicit. If you're loading labels from multiple namespaces (e.g., framework-shipped labels like `LightningDatatable`), you'd specify the namespace in the `useTranslation` hook:
+
+```typescript
+const { t } = useTranslation("c"); // custom labels
+const { t: tFw } = useTranslation("LightningDatatable"); // framework labels
+```
+
+For most bundles, a single `"c"` namespace is all you need.
+
+---
+
+## Related
+
+- [label-xml.md](label-xml.md): the Custom Labels metadata XML shape
+- [interpolation.md](interpolation.md): how `{0}/{1}` placeholders work
+- [verifying.md](verifying.md): the serve/verify flow
+- [gotchas.md](gotchas.md): silent-fail traps to avoid

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

@@ -0,0 +1,311 @@
+# Interpolation: how `{0}`, `{1}` placeholders work
+
+Salesforce Custom Labels use **positional interpolation**: `{0}`, `{1}`, `{N}` placeholders that get replaced with runtime values at render time. This is the same substitution syntax used by Apex `String.format` and LWC `@salesforce/label`, so one label works across all three frameworks.
+
+---
+
+## TLDR
+
+It's a string-replace. i18next finds every `{0}`, `{1}`, `{N}` in the cached label content and substitutes the value at that key from the second argument of `t()`.
+
+---
+
+## Basic example
+
+**Label:**
+```xml
+<labels>
+  <fullName>Greeting</fullName>
+  <value>Hello, {0}</value>
+</labels>
+```
+
+**Component:**
+```typescript
+const { t } = useTranslation("c");
+const userName = "Tosin";
+return <h1>{t("Greeting", { 0: userName })}</h1>;
+// → "Hello, Tosin"
+```
+
+---
+
+## How it works
+
+1. At boot, the Platform SDK's `SalesforceBackend` fetches the label content from the org via GraphQL
+2. i18next caches it: `{ "c:Greeting": "Hello, {0}" }`
+3. At render time, the component calls `t("Greeting", { 0: "Tosin" })`
+4. i18next's interpolator does:
+   ```javascript
+   template = "Hello, {0}";
+   template.replace("{0}", "Tosin");
+   // → "Hello, Tosin"
+   ```
+5. The resulting string renders to the DOM
+
+The configuration that makes this work is in `src/i18n/index.ts`:
+
+```typescript
+interpolation: {
+  escapeValue: false,
+  prefix: "{",   // scan for {X} placeholders
+  suffix: "}",
+},
+```
+
+i18next ships with `{{name}}`-style named interpolation by default. We override it to use Salesforce's `{0}` positional style so one label works across Apex, LWC, and React.
+
+---
+
+## Multiple placeholders
+
+**Label:**
+```xml
+<value>Failed to save {0}: {1}</value>
+```
+
+**Component:**
+```typescript
+t("Save_Failed", { 0: "Account", 1: "Permission denied" });
+// → "Failed to save Account: Permission denied"
+```
+
+Order in the object doesn't matter; the placeholder **number** is what binds:
+
+```typescript
+t("Save_Failed", { 1: "Permission denied", 0: "Account" }); // same result
+```
+
+---
+
+## Same placeholder used twice
+
+Salesforce labels sometimes reuse the same positional placeholder:
+
+**Label:**
+```xml
+<value>User {0} cannot edit {0}'s own profile</value>
+```
+
+**Component:**
+```typescript
+t("Profile_Edit_Error", { 0: "tosin" });
+// → "User tosin cannot edit tosin's own profile"
+```
+
+This is common when sentence structure differs across languages and the same value appears in different grammatical roles.
+
+---
+
+## Numeric and date values
+
+Placeholders accept any JavaScript value. The value's `toString()` is what gets interpolated:
+
+```typescript
+// Numbers
+t("Record_Count", { 0: 42, 1: 100 });
+// label: "Showing {0} of {1} records" → "Showing 42 of 100 records"
+
+// Dates (default JS toString, not localized)
+t("Last_Modified", { 0: new Date() });
+// label: "Last modified {0}" → "Last modified Mon Jul 07 2026 14:23:00 GMT-0700"
+```
+
+**Note:** This does **not** apply locale-aware formatting (e.g., `1.000,00` for German number formatting). For that, you'd use `Intl.NumberFormat` / `Intl.DateTimeFormat` separately and pass the **formatted string** as the placeholder value:
+
+```typescript
+const formattedCount = new Intl.NumberFormat(locale).format(count);
+t("Record_Count", { 0: formattedCount, 1: total });
+```
+
+The Platform SDK's `fetchI18nContext()` gives you `ctx.locale` and `ctx.currency` for feeding `Intl` formatters.
+
+---
+
+## Translations must preserve placeholders
+
+**English:**
+```xml
+<value>Failed to save {0}: {1}</value>
+```
+
+**Spanish translation:**
+```xml
+<label>Error al guardar {0}: {1}</label>
+```
+
+The placeholders stay as `{0}`, `{1}`; they can move (grammar might flip the order), but the **numbers must match**. If the Spanish translation says `{A}` or drops `{1}`, the substitution breaks.
+
+This is why Translation Workbench is valuable: it shows translators the placeholders and warns if they're missing.
+
+---
+
+## Failure modes
+
+### Missing placeholder value
+
+**Label:** `"Hello, {0} from {1}"`
+
+**Call:**
+```typescript
+t("Greeting", { 0: "Tosin" }); // forgot {1}
+// → "Hello, Tosin from {1}" (literal placeholder leaks)
+```
+
+There's no runtime error or console warning; the unsubstituted placeholder just renders as-is. This is a visual bug, not a crash.
+
+**Fix:** Always pass every placeholder the label expects. PR review catches this today (no build-time validation yet).
+
+### Missing label entirely
+
+```typescript
+t("Nonexistent_Key");
+// → "Nonexistent_Key" (literal key string)
+```
+
+This is the **unregistered manifest key** trap (see [gotchas.md](gotchas.md)): the label wasn't fetched, so i18next has nothing to interpolate.
+
+---
+
+## Worked examples by complexity
+
+### 1. No interpolation (most labels)
+
+**Label:** `"Welcome"`
+
+**Call:** `t("Welcome_Text")`
+
+**Result:** `"Welcome"`
+
+Most labels are just lookups, no placeholders.
+
+---
+
+### 2. Single value
+
+**Label:** `"You have {0} items"`
+
+**Call:** `t("Item_Count", { 0: 5 })`
+
+**Result:** `"You have 5 items"`
+
+---
+
+### 3. Error with context
+
+**Label:** `"{0} failed at step {1} for record {2}: {3}"`
+
+**Call:**
+```typescript
+t("Pipeline_Error", {
+  0: "OnboardingPipeline",
+  1: err.step,
+  2: record.name,
+  3: err.message,
+});
+```
+
+**Result:** `"OnboardingPipeline failed at step ValidateAccount for record Acme Corp: Missing tax ID"`
+
+One label, reusable across pipelines. Translated once. Engineers in any framework call it the same way.
+
+---
+
+### 4. Pluralization (leveraging i18next on top of positional)
+
+i18next has native pluralization support. For Salesforce labels, you author separate labels for each plural form:
+
+**Labels:**
+```xml
+<labels>
+  <fullName>Item_Count_one</fullName>
+  <value>You have {0} item</value>
+</labels>
+<labels>
+  <fullName>Item_Count_other</fullName>
+  <value>You have {0} items</value>
+</labels>
+```
+
+**Manifest:**
+```typescript
+export const labelManifest = [
+  "c:Item_Count_one",
+  "c:Item_Count_other",
+];
+```
+
+**Component:**
+```typescript
+t("Item_Count", { 0: count, count: count });
+// count = 1 → "You have 1 item"
+// count = 5 → "You have 5 items"
+```
+
+i18next reads the `count` arg and picks the `_one` or `_other` suffix per the English plural rules. The `0` arg drives substitution. The suffixes must be **lowercase** (`_one`, `_other`): i18next derives them from the browser's `Intl.PluralRules` categories, which are lowercase, and appends them verbatim to the key. A PascalCase `_One` label would never be found, and the label would render as its literal key name.
+
+Languages with more plural forms (Russian, Polish, Arabic) need more label variants, `_zero`, `_few`, `_many`, etc. Author them as separate Custom Labels with the appropriate lowercase suffixes.
+
+---
+
+## Why positional (`{0}`) instead of named (`{name}`)?
+
+**Portability.** Salesforce has three UI frameworks:
+- Apex (backend): `String.format(label, [arg0, arg1])`
+- LWC: `@salesforce/label/c.Save_Failed` with `{0}/{1}`
+- React UI Bundles: `t("Save_Failed", { 0: ..., 1: ... })`
+
+All three use the same Custom Labels metadata. If React used `{name}` syntax, the same logical string would need to be authored **twice**, once for Apex/LWC with `{0}`, once for React with `{name}`. Translators would maintain two formats. Engineers couldn't reuse strings across frameworks.
+
+With the bridge (`prefix: "{", suffix: "}"`), **one Custom Label serves all three**. Portability is the win.
+
+---
+
+## What the bridge doesn't do (not in MVP)
+
+- **Date/number formatting**: `{ 0: new Date() }` produces JS's default `toString`, not localized formatting. Wiring up `Intl.DateTimeFormat` / `Intl.NumberFormat` via i18next's `interpolation.format` callback is a separate design decision (not in the MVP scope).
+- **Type safety**: nothing checks that `Save_Failed` actually has 2 placeholders at build time. A build-time extractor could close this gap (future work).
+- **Escape for literal `{0}` in content**: i18next has escape options if labels genuinely need to contain literal curly braces. Edge case.
+
+---
+
+## Visual flow
+
+```text
+┌─────────────────────────────────────────────────┐
+│ 1. Custom Label (authored in Salesforce):      │
+│    "Failed to save {0}: {1}"                    │
+└─────────────────────────────────────────────────┘
+                       ↓
+              GraphQL fetch at boot
+                       ↓
+┌─────────────────────────────────────────────────┐
+│ 2. Cached in i18next memory:                    │
+│    { 'c:Save_Failed': "Failed to save {0}: {1}" }│
+└─────────────────────────────────────────────────┘
+                       ↓
+            Component calls t('Save_Failed',
+                              { 0: 'Account',
+                                1: 'Permission denied' })
+                       ↓
+┌─────────────────────────────────────────────────┐
+│ 3. i18next's interpolator does:                │
+│    template = "Failed to save {0}: {1}"         │
+│    template.replace('{0}', 'Account')           │
+│            .replace('{1}', 'Permission denied') │
+└─────────────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────────────┐
+│ 4. Output:                                      │
+│    "Failed to save Account: Permission denied"  │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Related
+
+- [i18n-setup.md](i18n-setup.md): the init file where the `prefix`/`suffix` are configured
+- [label-xml.md](label-xml.md): how to author labels with placeholders
+- [verifying.md](verifying.md): testing interpolated labels
+- [gotchas.md](gotchas.md): silent-fail traps