Skip to content

forcedotcom/sf-skills / plugins/builder/experience-react/skills/experience-ui-bundle-localize

experience-ui-bundle-localize

Verified

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.

references/react/interpolation.md

View on GitHub
# 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 [../common/gotchas.md](../common/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
- [../common/label-xml.md](../common/label-xml.md): how to author labels with placeholders
- [../common/verifying.md](../common/verifying.md): testing interpolated labels
- [../common/gotchas.md](../common/gotchas.md): silent-fail traps
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall