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
| Need |
Mechanism |
| User-facing UI string, translatable |
Custom Label |
| Configuration value (URL, toggle) |
Custom Metadata Type |
| Long dynamic email body |
Email Template or CMDT rich text |
| Runtime mutable string by admin |
Custom Setting or CMDT |
| Label over 1,000 chars |
Split or use CMDT |
Recommended Workflow
- Audit codebase for hard-coded strings in LWC, Apex, validation rules, email templates.
- Create labels with meaningful Names and filled Short Descriptions.
- Categorize labels by UI area or feature.
- Replace hard-coded strings with
System.Label / @salesforce/label / $Label references.
- Enable target languages; export STF for translators; import translated STF.
- Add CI check that flags new string literals in LWC templates and Apex error messages.
- Document naming convention and approval workflow for label additions.
Review Checklist
Salesforce-Specific Gotchas
- Renaming the label Name breaks Apex. References compile-fail. Always add a new label and deprecate.
- Labels are cached per session. Changing a value may not reflect until session reload; bust cache or test with a new session.
- STF export can omit new labels if not saved first. Save the label list before exporting.
Output Artifacts
| Artifact |
Description |
| Label catalog |
Name, value, category, languages, owner |
| Reference audit |
Files referencing each label |
| Translation plan |
Languages, translators, turnaround |
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
1---2name: custom-label-management3description: "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."4category: admin5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Operational Excellence8 - Scalability9tags:10 - custom-labels11 - i18n12 - translation13 - lwc14 - apex15triggers:16 - "how do i add a translatable string to a lightning web component"17 - "custom label versus custom metadata for configuration text"18 - "translation workbench custom label workflow for multi-language rollout"19 - "apex system.label reference fails after rename"20 - "1000 character limit on custom labels workaround"21 - "custom label deployment and packaging best practices"22inputs:23 - Text strings used in UI, Apex, or validation messages24 - Target languages and localization requirements25 - Packaging model (unlocked, managed, org-level)26outputs:27 - Custom Label catalog with categories28 - Translation workflow and translator handoff29 - Apex/LWC reference patterns30 - Deployment and packaging plan31dependencies: []32version: 1.1.033author: Pranav Nagrecha34updated: 2026-05-1935metadata:36 source: https://skillmd.com/skills/pranavnagrecha/custom-label-management37---3839# Custom Label Management4041Activate 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.4243## Before Starting4445- **Identify every hard-coded user-facing string.** LWC templates, Apex `addError` calls, validation rules, and email templates all accumulate string debt.46- **Know the 1,000-character limit per label.** Longer blocks need splitting or a Rich Text custom object.47- **Enable the Translation Workbench** and inventory target languages before exporting.4849## Core Concepts5051### Label vs Name vs Value5253Every 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.5455### Reference patterns5657- Apex: `System.Label.My_Label`58- LWC: `import LABEL from '@salesforce/label/c.My_Label';` (namespace `c` for local, custom namespace for package)59- Validation rule / formula: `$Label.My_Label`60- Visualforce: `{!$Label.My_Label}`6162### Translation Workbench6364Admin enables target languages; translators (or a translator profile) fill values per language. Export/import CSV/STF files for external translation services.6566### Packaging impact6768Labels travel with metadata. Managed-package labels are namespaced (`ns.My_Label`); unlocked packages and org-level labels are not.6970## Common Patterns7172### Pattern: Category-based organization7374Use categories like `Errors`, `UIButtons`, `Toast`, `EmailBody`. Filter the setup list during audits; Apex tools can scan by category prefix.7576### Pattern: LWC label import with local `labels` object7778```79import greeting from '@salesforce/label/c.Greeting';80import farewell from '@salesforce/label/c.Farewell';81export default class Hello extends LightningElement {82 labels = { greeting, farewell };83}84```8586Template: `{labels.greeting}`. Clean and renameable.8788### Pattern: Long-text overflow8990For 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.9192## Decision Guidance9394| Need | Mechanism |95|---|---|96| User-facing UI string, translatable | Custom Label |97| Configuration value (URL, toggle) | Custom Metadata Type |98| Long dynamic email body | Email Template or CMDT rich text |99| Runtime mutable string by admin | Custom Setting or CMDT |100| Label over 1,000 chars | Split or use CMDT |101102## Recommended Workflow1031041. Audit codebase for hard-coded strings in LWC, Apex, validation rules, email templates.1052. Create labels with meaningful Names and filled Short Descriptions.1063. Categorize labels by UI area or feature.1074. Replace hard-coded strings with `System.Label` / `@salesforce/label` / `$Label` references.1085. Enable target languages; export STF for translators; import translated STF.1096. Add CI check that flags new string literals in LWC templates and Apex error messages.1107. Document naming convention and approval workflow for label additions.111112## Review Checklist113114- [ ] No user-facing hard-coded strings in LWC templates115- [ ] No hard-coded strings in Apex `addError` calls or `System.debug`116- [ ] Short Description filled on every new label (translator context)117- [ ] Categories consistent across labels118- [ ] Translation Workbench enabled; STFs imported for each language119- [ ] Package/deployment plan includes labels120- [ ] Naming convention documented121122## Salesforce-Specific Gotchas1231241. **Renaming the label Name breaks Apex.** References compile-fail. Always add a new label and deprecate.1252. **Labels are cached per session.** Changing a value may not reflect until session reload; bust cache or test with a new session.1263. **STF export can omit new labels if not saved first.** Save the label list before exporting.127128## Output Artifacts129130| Artifact | Description |131|---|---|132| Label catalog | Name, value, category, languages, owner |133| Reference audit | Files referencing each label |134| Translation plan | Languages, translators, turnaround |135136## Related Skills137138- `admin/custom-metadata-types` — configuration data vs UI text139- `lwc/lwc-localization-i18n` — LWC-side language handling140- `devops/cicd-pipeline-design` — CI checks for new literals