Multi Language And Translation

Multi-Language and Translation

Use this skill when configuring Salesforce to support multiple languages for internal users or Experience Cloud site visitors. This covers enabling Translation Workbench, adding supported languages, translating custom labels, field labels, picklist values, page layout section names, and configuring the Experience Cloud language switcher.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the org edition — Translation Workbench requires Enterprise, Unlimited, Performance, or Developer Edition.
• Identify the languages to add using their Salesforce locale code (e.g., es for Spanish, fr for French, ar for Arabic).
• Determine what needs translating: field labels, picklist values, custom labels, validation rule error messages, page layout section names. Each has a different translation path.
• For RTL languages (Arabic, Hebrew), confirm the org has enabled RTL support and test the UI rendering — not all custom components support RTL automatically.

Core Concepts

Translation Workbench Architecture

Translation Workbench (Setup > Translation Workbench > Translation Settings) is the central management tool for Salesforce UI translations. Key concepts:

• Default language: The org's default language. All metadata is authored in this language.
• Supported languages: Languages you enable in Translation Workbench. Only supported languages are available to users and translatable via the Workbench.
• Translation override vs. auto-translation: Translations for standard Salesforce UI elements are provided by Salesforce for supported languages. Custom components (custom labels, custom field labels, picklist values) require manual entry or import.

Custom Label Translations

Custom Labels (Setup > Custom Labels) are the standard mechanism for translatable string constants used in Apex, Visualforce, and Flow. Each label supports translations per language:

1. Create the Custom Label with the English value.
2. Open the label, click "New Local Translations/Overrides".
3. Select the language, enter the translated value.

In Apex: System.Label.My_Label returns the translation for the running user's language. In Visualforce: {!$Label.My_Label} returns the translation. In Flow: Use the {!$Label.My_Label} merge field in text elements.

Picklist Value Translation

Picklist values are translated via Translation Workbench > Translate:

1. Select the entity type: "Picklist Value"
2. Select the object and picklist field
3. Enter translated values for each language

Critical rule: The picklist value API value (the stored database value) does not change when you add translations. Only the displayed label changes. Validation rules and Apex should use the API value, not the translated label.

Querying Translated Labels with toLabel()

Translation Workbench and custom labels translate what users see in the standard UI, but query results return the master (default-language) value by default. So an LWC or Apex controller that renders values from its own SOQL — a custom console list, a report-style component, an Experience Cloud data table — will show English to a Spanish user even when the translations exist. The toLabel() SOQL/SOSL function returns the translation for the running user's language instead.

• Wrap the field in the SELECT clause: SELECT Company, toLabel(Status) FROM Lead.
• Supported fields: regular, multiselect, division, and currency-code picklists; data category group and data category unique-name fields; and record type names (toLabel(RecordType.Name)).
• Any org can use toLabel(); it is most useful once Translation Workbench is enabled. When a value has no translation, it falls back to the master (default-language) value, so a single query serves every language.
• The SOSL equivalent lives in the RETURNING clause: FIND {Joe} RETURNING Lead(Company, toLabel(RecordType.Name)).

Query-clause restrictions (these are the ones that fail silently or won't compile):

• No ORDER BY on a toLabel() field — SOQL always sorts by the picklist's defined order, never by the translated text.
• Alias required when the same field appears twice — e.g. returning both the raw value (for logic) and the translated value (for display): SELECT Status, toLabel(Status) translatedStatus FROM Lead.
• You can filter a picklist on its label — WHERE toLabel(Status) = 'le Draft' matches the translated label. But LIKE only matches the label text, never the API name.
• You cannot filter on a translated record type name — filter on the master value or the record type Id instead.
• No toLabel() in a WHERE clause for division or currency ISO-code picklists.

This is the display-side complement to the API-value rule above: use the API value wherever a comparison drives behavior (Apex, validation rules, routing filters), and reach for toLabel() only when the goal is to show translated values in query output.

Experience Cloud Language Switcher

For Experience Cloud sites:

1. Enable Translation Workbench and add supported languages.
2. In Experience Builder, add the Language Switcher component to the site header.
3. In Site Settings, set the default language and enable language-specific content.
4. Translated content for Experience Cloud pages is managed via Content Management or by creating language variants of the site.

RTL Language Support

For Arabic (ar), Hebrew (iw/he), or other RTL languages:

• Salesforce Lightning Experience supports RTL layout natively when the user's language is set to a RTL locale.
• Custom LWC components may need CSS direction: rtl and text-align: start adjustments.
• Experience Cloud sites support RTL via the site-level language setting.

Common Patterns

Bulk Export/Import via Translation Workbench Spreadsheet

When to use: Large orgs with hundreds of custom labels, picklist values, or field labels to translate.

How it works:

1. Translation Workbench > Export Translations: select the language and metadata types to export.
2. The export generates a ZIP containing a bilingual tab-delimited text file.
3. Send the file to a translation service. They fill the translation column.
4. Import via Translation Workbench > Import Translations: upload the completed file.

Why not manual entry: Manual entry is impractical for large translation sets. The export/import workflow enables external translation vendors and version control of translated strings.

Validation Rule Error Message Translation

When to use: Validation rule error messages must display in the user's language.

How it works:

1. Write the validation rule error message using a Custom Label merge field: $Label.Account_Name_Required.
2. Create translations for that label in each supported language.
3. When the validation rule fires, the error message displays in the user's language.

Why not hardcode the message in the formula: A hardcoded message string in a validation rule formula cannot be translated.

Decision Guidance

Recommended Workflow

1. Enable Translation Workbench. Setup > Translation Workbench > Translation Settings > Enable.
2. Add supported languages. For each language, select it and set an active translator user (optional). Language becomes available to users and translatable.
3. Audit translatable components. List all custom labels, custom field labels, custom picklist values, page layout section names, and validation rule messages that need translation.
4. For code strings in Apex/Visualforce/Flow: Ensure all user-facing strings use Custom Labels (not hardcoded). Create translations for each label in each supported language.
5. For field/picklist labels: Enter translations via Translation Workbench > Translate, or use the bulk export/import workflow for large volumes.
6. Test each language. Create a test user with the target language locale. Log in as that user and verify that all translated elements display correctly in the target language.
7. For Experience Cloud: Add Language Switcher component to site header. Test the switcher and confirm page content changes language as expected.

Review Checklist

• Translation Workbench enabled and required languages added as Supported Languages
• All custom labels used for user-facing strings have translations for each supported language
• Picklist values translated — API values confirmed unchanged
• Validation rule error messages use Custom Labels (not hardcoded strings)
• Tested with a user whose profile language is set to each supported language
• Experience Cloud language switcher configured and tested (if applicable)
• RTL languages tested in relevant UI contexts — custom components checked for direction issues

Salesforce-Specific Gotchas

1. Picklist API value does NOT change with translation — Translations only affect the displayed label. Validation rules, Apex conditions, and SOQL WHERE clauses must use the API value (the English/default language value), not the translated label.
2. Translation Workbench export includes metadata you may not intend to translate — The export for a language includes all translatable metadata. Review the export carefully before sending to a vendor to avoid including internal/system labels that should not change.
3. RTL support requires more than enabling the language — Native Lightning Experience and standard components support RTL. Custom LWC components and Experience Cloud custom templates may need explicit CSS direction: rtl adjustments.
4. toLabel() has query-clause restrictions — see the Querying Translated Labels with toLabel() section above for the full list (no ORDER BY, no record-type-name filter, no WHERE on division/currency ISO-code picklists, alias-when-duplicated, LIKE matches label only). Treat it as a display-only projection.

Output Artifacts

Related Skills

• picklist-and-value-sets — picklist design and value management (upstream of translation)
• experience-cloud-security — Experience Cloud configuration (includes language/region settings)