Custom Labels
Custom Labels in Salesforce are admin-managed text strings stored centrally and referenced by code (Apex, Lightning Web Components, Aura Components, Visualforce, Flow) instead of hardcoding text.
Definition
Custom Labels in Salesforce are admin-managed text strings stored centrally and referenced by code (Apex, Lightning Web Components, Aura Components, Visualforce, Flow) instead of hardcoding text. Each Custom Label has a name (the API identifier code uses), a value (the actual text), an optional categorization, and translations for every language the org supports. Code references the Label by name; the platform serves the right translation based on the user's language preference.
Custom Labels exist because text in code is brittle. Hardcoding "Please enter a valid email address" in an Apex class works until the org needs Spanish or until the wording needs to change everywhere. Custom Labels move the text out of code and into a managed surface where translations live alongside the strings, admins can update wording without redeploying code, and the same Label can serve every code path that needs that string. They are the foundation of any serious localization or wording-governance strategy in a Salesforce org.
Why Custom Labels are the localization foundation under any multi-language org
Where Custom Labels live and how they are created
Setup, User Interface, Custom Labels. The page lists every Label with name, category, and value. New Custom Label opens a form for name (API identifier, max 80 chars), value (max 1,000 chars), category (optional grouping), protected (true means managed package code only, false means org code). Once saved, the Label is referenceable in Apex (System.Label.LabelName), in LWC (import LabelName from @salesforce/label/c.LabelName), in Aura ({!$Label.c.LabelName}), in Visualforce ({!$Label.LabelName}), and in Flow (text field with $Label.c.LabelName reference).
Translation Workbench and the localization layer
Setup, Translation Workbench enables per-language translations. Each Custom Label can have a translation for every language the org has enabled. When a user in Spanish sees a message that references the Label, the platform serves the Spanish translation. When the same Label fires for an English user, the English value serves. The Translation Workbench is the central surface for adding and editing translations; translators (a special permission) can update translations without admin access to code.
Where Custom Labels show up in code
Apex: System.Label.MyLabel returns the right-language string based on the running user's language. LWC: import the Label as a JavaScript module, use as a template literal. Aura: $Label.c.MyLabel inline in markup. Visualforce: {!$Label.MyLabel}. Flow: the Label reference syntax in any text field that supports formula resolution. The pattern is consistent: the Label is the variable, the platform handles language resolution at runtime. The only code change needed for a wording update is to the Label's value; the code itself stays untouched.
Categories and the Label organization
Each Custom Label can belong to one or more categories. Categories are admin-defined groupings: error messages, button labels, email subject lines, validation messages. The categorization helps admins find Labels in the org-wide list (which can grow to thousands of entries) and helps the translation workflow (a translator can work through Email Subject Lines as a batch). Categories are optional but recommended; orgs without categorization end up with flat Label lists that nobody can navigate.
The protected flag and managed package interaction
Custom Labels can be marked Protected (true or false). Protected Labels in a managed package are accessible only from the package code; org-level code and other packages cannot reference them. This is the right pattern for ISV packages that want to lock down their internal strings. Org-level Custom Labels are typically protected=false so org code and admin tools can reference them freely. The flag is set at Label creation; changing later is restricted in packaged contexts.
When Custom Labels are the wrong tool
Three patterns are better served by other constructs. Validation rule error messages should live on the Validation Rule itself (which has its own error message field that respects translation). Field labels should be set on the field directly, not pointed at a Label. Picklist values should be set on the picklist; the Translation Workbench supports per-language translations of picklist values directly. Use Custom Labels for code-emitted strings; use the appropriate construct for everything else.
Audit, maintenance, and the Label inventory
Custom Labels accumulate. Labels created for features that were retired persist; orphaned Labels clutter the list and confuse new developers. The audit discipline: quarterly review of unused Labels (no code references in the past year), document each Label's owner and purpose, retire those that no one uses. The Labels list is searchable but the search does not show usage; building a separate inventory with owner and references is the operational discipline that keeps the surface manageable.
How to use Custom Labels for code-emitted strings
The successful pattern: any user-facing string in code goes through a Custom Label. The cost is one Setup record per string; the benefit is updateable wording, multi-language support, and a single surface for translators.
- Identify the string in code that needs translation or governance
Error messages, button labels, dialog titles, email subjects emitted from Apex or LWC. Each candidate becomes a Label.
- Create the Custom Label
Setup, Custom Labels, New. Name per convention (org_prefix_purpose: SDR_INVALID_EMAIL, OPS_RECORD_NOT_FOUND). Enter the default value. Pick a category.
- Add translations via Translation Workbench
For each language the org supports, enter the translated string. Translators can do this without admin access to code.
- Reference the Label in code
Apex: System.Label.SDR_INVALID_EMAIL. LWC: import from @salesforce/label/c.SDR_INVALID_EMAIL. Replace the hardcoded string with the Label reference.
- Deploy and verify
Deploy through the normal pipeline. Verify in the UI that the Label serves correctly in each supported language.
- Document the Label in the inventory
Name, purpose, owner, code references. The inventory is what saves future developers from re-creating duplicate Labels for the same string.
- Audit unused Labels quarterly
Pull the Labels list. Identify those with no code references in the past year. Retire after confirming non-use.
The API identifier code references. Convention-based naming is essential at scale.
The string served when no translation matches the user's language.
Admin-defined grouping for organization and translator workflow.
Whether the Label is accessible from non-package code. Default false for org Labels; true for managed-package internals.
Per-language values configured in Translation Workbench.
- Custom Labels are not the right tool for validation rule error messages or picklist values. Use the construct-native fields, which have their own translation paths.
- Label names cannot be changed after deployment to a packaged context. Pick the name carefully at creation.
- Orphaned Labels accumulate. Quarterly cleanup is the discipline that keeps the surface manageable.
- Translation Workbench access is a separate permission. Translators need it explicitly; without it, only admins can update translations.
- Hardcoded strings in code bypass Custom Labels. The pattern only works if developers adopt the convention; without code-review enforcement, strings get hardcoded anyway.
Trust & references
Cross-checked against the following references.
- Custom Labels referenceSalesforce
- Translation Workbench referenceSalesforce
Straight from the source - Salesforce's reference material on Custom Labels.
- Custom LabelsSalesforce Help
- Translation WorkbenchSalesforce Help
- Apex Custom Label ReferenceSalesforce Developers
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What are Custom Labels?
Q2. How are Custom Labels referenced from Apex?
Q3. Why use Custom Labels instead of hardcoded strings?
Discussion
Loading discussion…