> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/developers-headless/studio/template-builder/editor-labels.md).

# Editor labels

`labels` renames the editor's own vocabulary to match your domain. An ad platform can call layouts "ads", layers "ad content" and variables "product fields", and the editor uses those words in every heading, menu, dialog, empty state and tooltip that names them.

```html
<sfx-template-builder
  labels='{
    "layout":   { "one": "ad",            "other": "ads" },
    "layer":    { "one": "ad content",    "other": "ad content" },
    "variable": { "one": "product field", "other": "product fields" },
    "sourceType": "Value source",
    "manualSource": "Fixed value"
  }'
  ...
></sfx-template-builder>
```

Or as a property:

```ts
builder.labels = { layout: { one: 'ad', other: 'ads' } }
```

{% hint style="info" %}
**Wording only.** The saved template, the render query and the URL parameters are unaffected. A template built under renamed labels opens unchanged in any other editor, and `$layout` is still `$layout`.
{% endhint %}

### Terms

A term renames a concept everywhere it appears, including inside sentences: with `layout` renamed, "No layouts yet. Click + Add to create one." reads "No ads yet. Click + Add to create one."

| Key        | Default                  | Where it appears                                                                                                                                                            |
| ---------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layout`   | `layout` / `layouts`     | The layouts list and its menu, the New layout and Add first layout dialogs, the empty canvas, the preview switcher, the properties panel badge, the save-blocked message    |
| `layer`    | `layer` / `layers`       | The Layers tab, the layer menu, the properties panel badges (**Text layer**, **Image layer**, **Shape layer**), the source-image picker, "Base layer positioning on layout" |
| `variable` | `variable` / `variables` | The Variables tab, the New variable dialogs, the text editor's insert menu, the slug switcher, delete confirmations, the properties panel badge                             |

Each term takes both forms, `one` for the singular and `other` for the plural. Give the same word twice for a mass noun, as `ad content` above. A term missing either form is ignored and that concept keeps its default wording. The editor does not guess a plural.

**Write terms the way they read mid-sentence**: lowercase, unless the word is a proper noun or an acronym. The editor capitalizes the first letter where a term starts a heading ("Ads", "SKU fields"), and never lowercases anything, so `SKU field` stays intact. Terms are capped at 30 characters, labels at 60, and `insertVariableButton` at 24 because it sits in the compact text toolbar.

The editor never puts "a" or "an" in front of a term, so a word starting with a vowel reads correctly without any extra configuration.

### Labels

A label is shown as-is in one place, the way `custom-metadata-label` is.

| Key                    | Default                          | What it names                                                                                                                               |
| ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceType`           | Source type                      | The picker that chooses where a text variable's value comes from                                                                            |
| `manualSource`         | Manual                           | The source whose value is typed in the editor or supplied in the render query. Image variables keep **Image URL**                           |
| `insertVariableButton` | the `variable` term, capitalized | The text editor toolbar's insert button. Set it when an action reads better than a noun - `Customize text`. Its tooltip still uses the term |

The **Custom metadata** source keeps its own attribute, [`custom-metadata-label`](https://docs.scaleflex.com/developers-headless/studio/template-builder/custom-metadata.md#naming-the-source).

### Choosing words

* **Keep the names distinct.** A variable term and a source label that share a word read badly next to each other. With variables called "product fields" and the custom-metadata source also called "Product field", a variable's panel says **Value source: Product field** about something that is itself a product field. Rename one of them.
* **Check the compounds.** A layer term appears after a layer kind, as in **Image layer**. `ad content` gives **Image ad content**, which reads fine; some words do not.
* **Only the editor is renamed.** The public Template Builder documentation and support answers keep the standard words. If your authors will read the docs, tell them which of your words maps to which. The Variations screen keeps the standard words too. The widget never shows that screen, so this only matters if you frame the whole app.

### Changing and withdrawing labels

Assign a new object to change the labels in a running editor. Lit compares by identity, so mutating the object you passed does nothing. Assigning `{}`, or removing the attribute, restores every default.

Anything the editor cannot use is dropped entry by entry. An unknown key, a value that is not a string, or a control character costs that entry, not the others.

### Compatibility

`labels` needs a deployment on protocol v5 and the widget release that follows 0.5.0. An older deployment or an older pinned widget ignores it, and the editor keeps its default wording. A host integrating without the widget sends the same object as `labels` in `design-templates:host:config`; see [the postMessage protocol](https://docs.scaleflex.com/developers-headless/studio/template-builder/postmessage-protocol.md).
