Home / admin / custom-label-management

custom-label-management

Custom Labels for i18n, configuration strings, and UI text: translation workbench, Apex System.Label, LWC @salesforce/label imports, 1,000-char limit. NOT for translating picklist values, field labels or layouts — use admin/multi-language-and-translation. NOT for config values in custom metadata or custom settings — use admin/custom-metadata-types.

• v1.2.0
• Salesforce Spring '25+
• Updated 2026-09-04
• Operational Excellence
• Scalability

• custom-labels
• i18n
• translation
• lwc
• apex

Open the skill folder on GitHub

Custom Label Management

Activate when hard-coded strings appear in Apex, LWC, validation rules, or email templates that will need to be translated, reviewed for tone, or changed without code. Custom Labels are the canonical Salesforce mechanism for externalizing text and pushing it through the Translation Workbench.

Before Starting

• Identify every hard-coded user-facing string. LWC templates, Apex addError calls, validation rules, and email templates all accumulate string debt.
• Know the 1,000-character limit per label. Longer blocks need splitting or a Rich Text custom object.
• Enable the Translation Workbench and inventory target languages before exporting.

Questions to Ask Before Configuring

Ask these before the first <labels> element is written. Every row maps to a CustomLabel field that Metadata API marks Required or to a documented platform behaviour — skip a row and the file still deploys, then misbehaves.

What a proper configuration adds over just creating the labels: the file deploys alongside the code that references it, every label carries the translator context and packaging flag the platform requires, and the translation files exist per locale instead of silently falling back to the source language.

Core Concepts

Label vs Name vs Value

Every custom label has a Name (API, immutable once referenced), Short Description (required, hint for translators), Categories (a comma-separated grouping string — see the field table below), Value (the default-language string), and per-language translations. Never rename Name — Apex references break.

The CustomLabel fields Metadata API actually defines

Source: Metadata API Developer Guide, CustomLabels → CustomLabel field table (api_meta.txt:41187-41221). Note categories is comma-separated per the guide, not semicolon-separated.

Where the metadata lives

• Master values: a single CustomLabels.labels file — every label in the org

  shares it (api_meta.txt:41165).

• Translations: translations/<localeCode>.translation, one file per locale,

  containing <customLabels> entries with <name> and <label> (api_meta.txt:135574-135577, api_meta.txt:135930-135937).

• Packaged translations use pkgNamespace__localeCode.translation

  (api_meta.txt:135576-135577).

Reference patterns

• Apex: System.Label.My_Label
• LWC: import LABEL from '@salesforce/label/c.My_Label'; (namespace c for local, custom namespace for package)
• Validation rule / formula: $Label.My_Label
• Visualforce: {!$Label.My_Label}
• Apex, dynamic: Label.get(namespace, label, language) and

  Label.translationExists(namespace, label, language) — resolved at run time, so a missing label is silence rather than a compile error (apexrefguide.txt:220031-220034)

UNVERIFIED (2026-09-04): only the Apex forms above are grounded in the sources used for this revision (apexdev.txt:7246-7250, apexrefguide.txt:220031-220037). The LWC @salesforce/label/c.<Name> import specifier is not re-grounded because the LWC Developer Guide is not in the extracted corpus, and the corpus shows the $Label merge field only in its namespaced form inside a Gift Entry template (api_meta.txt:78590) — never in a validation-rule or formula context. Confirm both against their own guides before shipping; the full markers and what they rest on are in references/metadata-examples.md.

Translation Workbench

Admin enables target languages; translators (or a translator profile) fill values per language. Export/import CSV/STF files for external translation services. The Workbench side — enabling locales, the picklist and field-label surfaces, and toLabel() in SOQL — belongs to admin/multi-language-and-translation; this skill owns the label's own lifecycle and the Translations metadata that carries its translated value.

Packaging impact

Labels travel with metadata. Managed-package labels are namespaced (ns.My_Label); unlocked packages and org-level labels are not. The protected flag is the packaging contract: protected labels "can't be linked to or referenced by components created in the installing organization" (api_meta.txt:41203-41206), and Apex "can't access labels that are protected in a different namespace" (apexrefguide.txt:220008-220009). It is inert in an unpackaged org, which is why it gets set wrong — see references/gotchas.md Gotcha 10.

Common Patterns

Pattern: Category-based organization

Use categories like Errors, UIButtons, Toast, EmailBody. Filter the setup list during audits; Apex tools can scan by category prefix.

Pattern: LWC label import with local labels object

import greeting from '@salesforce/label/c.Greeting';
import farewell from '@salesforce/label/c.Farewell';
export default class Hello extends LightningElement {
    labels = { greeting, farewell };
}

Template: {labels.greeting}. Clean and renameable.

Pattern: Long-text overflow

For strings over 1,000 chars (complex email body), split into My_Long_Text_Part1, My_Long_Text_Part2 and concatenate. Alternatively, store in a Custom Metadata Type Rich Text field.

Decision Guidance

Recommended Workflow

1. Inventory and disposition. Fill

   templates/custom-label-management-template.md with the answers to Questions to Ask Before Configuring and one row per hard-coded string found in .cls, .trigger, LWC .html/.js, .flow-meta.xml and validation rules. Anything code branches on leaves for admin/custom-metadata-types.

2. Retrieve the current label set before editing. CustomLabels is one

   file for the whole org, so every deploy is a whole-set write and a stale copy silently reverts other people's values. Use the retrieve command and manifest in references/metadata-examples.md ("Retrieve, lint, deploy"), and note the categories already in use.

3. Author the <labels> entries. Copy the shape from

   references/metadata-examples.md — fullName, value, language, protected, shortDescription, categories on every label, not just the Required minimum.

4. Wire the consumers in the same change. Apex System.Label.X, LWC

   @salesforce/label/c.X, Flow and formula $Label.X. Read references/gotchas.md Gotchas 2 and 6 first — the compile-time binding and the whole-file replacement rule decide the deployment shape.

5. Lint before deploying. Run

   python3 scripts/check_custom_label_management.py --manifest-dir force-app/main/default. Clear every ERROR (duplicate fullName, over-length value); triage WARN (missing shortDescription, undefined label reference) and INFO (uncategorised label, label referenced nowhere).

6. Deploy labels and consumers as one payload, then author

   translations/<locale>.translation-meta.xml per enabled locale — see references/metadata-examples.md and admin/multi-language-and-translation for the Translation Workbench side.

7. Verify per locale. Follow the verification step in

   references/metadata-examples.md: log in as a user whose LanguageLocaleKey is the target locale and confirm each consumer surface, because a missing translation renders the source value with no error.

Review Checklist

• [ ] No user-facing hard-coded strings in LWC templates
• [ ] No hard-coded strings in Apex addError calls or System.debug
• [ ] Short Description filled on every new label (translator context)
• [ ] Categories consistent across labels
• [ ] Translation Workbench enabled; STFs imported for each language
• [ ] Package/deployment plan includes labels
• [ ] Naming convention documented

Salesforce-Specific Gotchas

1. Renaming the label Name breaks Apex. References compile-fail. Always add a new label and deprecate.
2. Labels are cached per session. Changing a value may not reflect until session reload; bust cache or test with a new session.
3. STF export can omit new labels if not saved first. Save the label list before exporting.

Output Artifacts

Reference Files

Related Skills

• admin/custom-metadata-types — configuration data vs UI text; where a value code branches on belongs
• admin/multi-language-and-translation — the Translation Workbench side: enabling locales, picklist and field-label translation, toLabel() in SOQL
• devops/metadata-api-retrieve-deploy — retrieve/deploy mechanics for the single-file CustomLabels type
• devops/destructive-changes-deployment — removing a label after its references are gone

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/custom-label-management-template.md
• scripts/check_custom_label_management.py