Salesforce Localization: Translation Workbench, Metadata, and Best Practices

Salesforce Localization: Translation Workbench, Metadata, and Best Practices

Salesforce is used by organizations worldwide, and its localization capabilities are built into the platform. From custom labels and field names to validation error messages and Lightning component text, Salesforce provides tools to translate virtually every user-facing string.

This guide covers the built-in Translation Workbench, custom label management, metadata translation, and patterns for integrating Salesforce localization with external translation management systems.

Salesforce Language Support

Salesforce distinguishes between three levels of language support:

• Fully supported languages — The platform UI, help text, and standard features are fully translated. Examples: English, Spanish, French, German, Japanese, Chinese (Simplified and Traditional), Korean, Portuguese (Brazilian).
• End-user languages — Users can select these as their personal language, and custom translations are displayed. Standard Salesforce UI remains in the closest fully supported language.
• Platform-only languages — Available for custom translations but not for standard Salesforce UI elements.

The exact list of supported languages is maintained in Salesforce's official documentation and varies by edition.

Translation Workbench

Translation Workbench is Salesforce's built-in tool for managing translations. It provides a web interface where translators can enter translations for custom metadata.

Enabling Translation Workbench

1. Navigate to Setup → Translation Workbench → Translation Settings
2. Click Enable
3. Add the languages you need to support
4. Assign translators to specific languages

Once enabled, Translation Workbench allows translating:

• Custom field labels and help text
• Custom object names and tab labels
• Picklist values
• Record types
• Validation rule error messages
• Page layout section headers
• Custom buttons, links, and actions
• Lightning app names and descriptions

What Translation Workbench Covers

Translation Workbench handles metadata translations — the labels, descriptions, and error messages that define your Salesforce org's configuration. It does not handle:

• Record data — The actual data stored in records (account names, opportunity descriptions) is not managed by Translation Workbench.
• Visualforce page content — Static text in Visualforce pages requires custom labels.
• Lightning Web Component text — LWC text requires custom labels or i18n patterns.

Custom Labels

Custom Labels are the primary mechanism for translatable strings in Salesforce custom code (Apex, Visualforce, LWC, Aura).

Creating Custom Labels

1. Navigate to Setup → Custom Labels
2. Click New Custom Label
3. Enter the label name, category, and default value
4. Add translations for each supported language

Using Custom Labels in Code

In Apex:

String message = System.Label.Welcome_Message;

In Lightning Web Components:

import welcomeMessage from '@salesforce/label/c.Welcome_Message';

export default class MyComponent extends LightningElement {
  label = { welcomeMessage };
}

<template>
  <p>{label.welcomeMessage}</p>
</template>

In Visualforce:

<apex:outputText value="{!$Label.Welcome_Message}" />

Custom Label Limits

Salesforce imposes limits on custom labels:

• Maximum 5,000 custom labels per org
• Each label value can be up to 1,000 characters
• Label names must be unique within the org
• Labels can be packaged and distributed with managed packages

For organizations with large translation needs, the 5,000 label limit can become a constraint. Plan label names carefully and reuse labels across components where the same text appears.

Metadata API for Translation

For programmatic access to translations, Salesforce provides the Metadata API with the Translations and CustomLabels metadata types.

Exporting Translations

Using the Salesforce CLI (sf/sfdx):

# Retrieve translations for a specific language
sf project retrieve start --metadata Translations:fr

# Retrieve all custom labels
sf project retrieve start --metadata CustomLabels

This produces XML files that can be processed by external tools:

<!-- translations/fr.translation-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<Translations xmlns="http://soap.sforce.com/2006/04/metadata">
  <customLabels>
    <label>Bienvenue dans notre application</label>
    <name>Welcome_Message</name>
  </customLabels>
</Translations>

Importing Translations

After translating the XML files, deploy them back:

sf project deploy start --source-dir force-app/main/default/translations

This API-based workflow enables integration with external TMS platforms. The typical flow:

1. Export translation metadata from Salesforce
2. Convert to a format the TMS accepts (XLIFF, JSON, CSV)
3. Translators work in the TMS
4. Convert completed translations back to Salesforce XML
5. Deploy via Metadata API

Best Practices

Organize Labels by Feature

Use a consistent naming convention with prefixes:

Checkout_Button_Pay
Checkout_Error_CardDeclined
Checkout_Success_Message
Profile_Label_FirstName
Profile_Label_LastName

This makes labels easier to find, translate in context, and manage at scale.

Separate UI Text from Business Logic

Keep translatable strings in Custom Labels rather than hardcoding them in Apex or JavaScript. This applies even for error messages:

// Avoid this
throw new AuraHandledException('An error occurred');

// Use this instead
throw new AuraHandledException(System.Label.Generic_Error_Message);

Test with Non-Latin Scripts

Verify that your layouts handle:

• German and Finnish — Long compound words that may overflow containers
• Japanese and Chinese — Characters that may render at different widths
• Arabic and Hebrew — Right-to-left (RTL) text direction
• Thai — Text without word boundaries that may affect line breaking

Handle Data Localization Separately

For translating record-level data (such as product names in a product catalog), consider:

• Formula fields that select the correct translation based on the user's language
• Custom objects with a translation-table pattern (similar to the database localization strategies)
• External content management through integration with a headless CMS or TMS

Frequently Asked Questions

Can I use Translation Workbench in all Salesforce editions?

Translation Workbench is available in Enterprise, Performance, Unlimited, and Developer editions. It is not available in Essentials or Professional editions.

How do I handle languages not supported by Salesforce?

For platform-only or unsupported languages, you can still create Custom Labels with translations. The standard Salesforce UI will display in the nearest supported language, but your custom components and pages will show the correct translations.

What is the difference between Translation Workbench and Custom Labels?

Translation Workbench translates metadata — field labels, picklist values, page layouts. Custom Labels are user-defined strings for use in custom code (Apex, LWC, Visualforce). Both are needed for a fully localized Salesforce org.

Can I automate Salesforce translation workflows?

Yes. The Metadata API allows programmatic export and import of translations. CI/CD tools like Salesforce CLI, GitHub Actions, and dedicated Salesforce DevOps platforms can automate the export → translate → import cycle.