Custom Label Management

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.

Core Concepts

Label vs Name vs Value

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

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}

Translation Workbench

Admin enables target languages; translators (or a translator profile) fill values per language. Export/import CSV/STF files for external translation services.

Packaging impact

Labels travel with metadata. Managed-package labels are namespaced (ns.My_Label); unlocked packages and org-level labels are not.

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. Audit codebase for hard-coded strings in LWC, Apex, validation rules, email templates.
2. Create labels with meaningful Names and filled Short Descriptions.
3. Categorize labels by UI area or feature.
4. Replace hard-coded strings with System.Label / @salesforce/label / $Label references.
5. Enable target languages; export STF for translators; import translated STF.
6. Add CI check that flags new string literals in LWC templates and Apex error messages.
7. Document naming convention and approval workflow for label additions.

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

Related Skills

• admin/custom-metadata-types — configuration data vs UI text
• lwc/lwc-localization-i18n — LWC-side language handling
• devops/cicd-pipeline-design — CI checks for new literals