forcedotcom/sf-skills / plugins/builder/experience-react/skills/experience-ui-bundle-localize
experience-ui-bundle-localize
VerifiedMUST 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.9 KB |
| references/angular/check-i18n-wired.shexecutable | script | 8.9 KB |
| references/angular/i18n-setup.md | markdown | 10.2 KB |
| references/angular/interpolation.md | markdown | 6.0 KB |
| references/angular/localize.md | markdown | 5.4 KB |
| references/common/gotchas.md | markdown | 14.5 KB |
| references/common/label-xml.md | markdown | 11.9 KB |
| references/common/platform-sdk-i18n.md | markdown | 7.6 KB |
| references/common/verifying.md | markdown | 15.0 KB |
| references/react/check-i18n-wired.shexecutable | script | 11.5 KB |
| references/react/i18n-setup.md | markdown | 10.7 KB |
| references/react/interpolation.md | markdown | 10.2 KB |
| references/react/localize.md | markdown | 3.8 KB |
| scripts/check-manifest-registered.shexecutable | script | 8.2 KB |
| scripts/check-org-api-version.shexecutable | script | 2.1 KB |
| scripts/detect-bundle-type.shexecutable | script | 6.4 KB |
| scripts/detect-framework.shexecutable | script | 2.2 KB |
| scripts/tests/test-detect-bundle-type.shexecutable | script | 9.1 KB |
references/angular/interpolation.md
View on GitHub# 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |