LanguageSettings Metadata Type in SFDX

Architectural Overview#

The LanguageSettings metadata type manages internationalization (i18n), Translation Workbench activation, and supported organizational languages in Salesforce. In multinational enterprises, global user bases operate across diverse native languages—such as Japanese, German, Spanish, French, and Simplified Chinese—requiring localized field labels, picklist values, and help text.

Architecturally, LanguageSettings is the foundational prerequisite for all translation and localization metadata. Enabling Translation Workbench through this setting unlocks the deployment of Translations, CustomObjectTranslation, and localized CustomLabel records. Without first applying LanguageSettings, any CI/CD pipeline attempting to deploy localized metadata will fail with TranslationWorkbenchNotEnabled errors.

Directory and File Conventions#

In Salesforce DX source format, LanguageSettings is represented as a single XML file within the settings directory:

Key Metadata Fields#

The XML schema for LanguageSettings controls Translation Workbench and data translation switches:

Declarative XML and Package Manifest Examples#

Source XML (Language.settings-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<LanguageSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableTranslationWorkbench>true</enableTranslationWorkbench>
    <enableDataTranslation>true</enableDataTranslation>
    <enableEndUserLanguages>true</enableEndUserLanguages>
</LanguageSettings>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Language</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment#

To retrieve LanguageSettings using the Salesforce CLI:

# Retrieve settings directly
sf project retrieve start --metadata Settings:Language

# Retrieve using manifest
sf project retrieve start --manifest manifest/package.xml

To deploy LanguageSettings to a target environment:

# Deploy to designated org
sf project deploy start \
  --metadata Settings:Language \
  --target-org uat \
  --wait 10

Senior Architect Deployment Best Practices and Gotchas#

Dependency Ordering in Global Deployments#

Translation metadata has an uncompromising dependency on LanguageSettings. In continuous delivery pipelines:

1. Phase 1: Deploy Settings:Language to activate Translation Workbench.
2. Phase 2: Deploy CustomObject, CustomField, and GlobalValueSet metadata.
3. Phase 3: Deploy CustomObjectTranslation and Translations language files.

Scratch Org Configuration#

For automated regression testing of multi-language implementations, enable Translation Workbench in project-scratch-def.json:

{
  "orgName": "Global Multilingual Scratch Org",
  "edition": "Enterprise",
  "features": ["TranslationWorkbench"],
  "settings": {
    "languageSettings": {
      "enableTranslationWorkbench": true,
      "enableDataTranslation": true,
      "enableEndUserLanguages": true
    }
  }
}

Frequently asked questions

What does LanguageSettings control in Salesforce?

It configures Translation Workbench enablement, active organizational languages, and end-user multilingual capabilities.

Where is LanguageSettings stored in an SFDX project?

It is stored under force-app/main/default/settings as Language.settings-meta.xml and retrieved as Settings:Language.

Why is LanguageSettings required before deploying translations?

Translation Workbench must be enabled before custom label or field translations in specific locales can be deployed.

Can LanguageSettings be deployed to scratch orgs?

Yes, by adding TranslationWorkbench to features and defining languageSettings in project-scratch-def.json.