The labels extension is a Data SDK extension that reads custom labels from your org. Import it from @salesforce/platform-sdk/data/extensions and attach it to the SDK.
The labels extension requires Salesforce API version 64.0 or later. See Minimum API Version.
1import { createDataSDK } from "@salesforce/platform-sdk/data";
2import { labels } from "@salesforce/platform-sdk/data/extensions";
3
4const sdk = await createDataSDK({ extensions: [labels({ namespace: "MyApp" })] });
5
6// Fall back to the label name when a label doesn't resolve
7const greeting = (await sdk.ext.labels.get?.("greeting")) ?? "greeting";
8
9// Override the configured options for a single call
10const french = await sdk.ext.labels.get?.("greeting", { locale: "fr" });
11
12// Resolve several labels in one batched load
13const many = await sdk.ext.labels.getAll?.(["greeting", "farewell"]);Creates the labels extension. Pass the optional config parameters to set default options for every call. Omit config to use the built-in defaults.
config is of type LabelsOptions.
Sets where labels are read from and how they resolve. Supply these options when you configure the extension to set defaults, and again per call to override them for that call. Each field resolves independently as call value, then configured value, then built-in default.
| Parameter | Type | Description |
|---|---|---|
namespace | string | The custom-label namespace to read from. To use the server’s default namespace (c), omit it or pass an empty string. |
locale | string | The target locale, such as fr or en-US. To use the logged-in user’s locale, omit it or pass an empty string. |
fallback | LabelFallback | Specifies how the server resolves a label that has no translation for the requested locale. Defaults to BASE_VALUE. |
Sets how the server resolves a label that has no translation for the requested locale.
1type LabelFallback = "BASE_VALUE" | "USER_DEFAULT" | "NONE";BASE_VALUE—Returns the org-default (base) value. This is the default.USER_DEFAULT—Falls back to the logged-in user’s language first, then the base value.NONE—Doesn’t fall back. A label with no translation for the locale is treated as unresolved, so it’s absent from the result.The API returned under sdk.ext.labels. Both methods are optional and are absent on a surface whose Data SDK has no graphql. Use optional chaining (sdk.ext.labels.get?.()) to account for surfaces that don’t support them.
Resolves a single label. Returns its value, or undefined if the server doesn’t resolve it.
1get?(name: string, options?: LabelsOptions): Promise<string | undefined>;| Parameter | Type | Description |
|---|---|---|
name | string | The developer name of the label to resolve. |
options | LabelsOptions | Optional. Per-call overrides of the configured options. |
Because an unresolved label returns undefined, provide your own fallback where you need one.
1const greeting = (await sdk.ext.labels.get?.("greeting")) ?? "greeting";Resolves several labels in one batched load. Returns a map keyed only by the names that resolved. A name that doesn’t resolve is absent from the map, which matches get() returning undefined.
1getAll?(names: readonly string[], options?: LabelsOptions): Promise<Record<string, string>>;| Parameter | Type | Description |
|---|---|---|
names | readonly string[] | The developer names of the labels to resolve. Names are deduped internally, so order and duplicates don’t matter. |
options | LabelsOptions | Optional. Per-call overrides of the configured options. |
Use getAll() for a bounded label set, such as an app’s manifest of dozens to low hundreds of labels. Names are split into batches of 100, the server’s per-call limit, and fetched concurrently. If you expect to resolve thousands of labels at once, we recommend that you batch, cache, or throttle the calls in your own code.
j