Translations Metadata Type in SFDX & Metadata API

Why the Translations Metadata Type Is Essential for Global Orgs#

While CustomObjectTranslation handles object-level fields and validation rules, Translations (translations/<lang>.translation-meta.xml) is the central translation hub for org-wide, non-object metadata. Whenever you localize a Lightning Web Component via @salesforce/label/c.MyLabel or localize a multi-language customer Screen Flow, those translations live inside translations/<lang>.translation-meta.xml.

What Is Stored Inside translations/<lang>.translation-meta.xml?#

Real-World XML Example (translations/es.translation-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Translations xmlns="http://soap.sforce.com/2006/04/metadata">
    <customApplications>
        <label>Consola de Operaciones Comerciales</label>
        <name>Commercial_Operations_Console</name>
    </customApplications>
    <customLabels>
        <label>Su solicitud ha sido enviada para aprobación.</label>
        <name>Approval_Submitted_Toast_Message</name>
    </customLabels>
    <customTabs>
        <label>Panel de Facturación</label>
        <name>Billing_Dashboard_Tab</name>
    </customTabs>
    <flowDefinitions>
        <flows>
            <fullName>Customer_Onboarding_Screen_Flow</fullName>
            <label>Registro de Nuevo Cliente</label>
            <screens>
                <fields>
                    <name>Company_Tax_ID_Input</name>
                    <fieldText>Número de Identificación Fiscal (NIF)</fieldText>
                </fields>
                <name>Customer_Details_Screen</name>
            </screens>
        </flows>
        <fullName>Customer_Onboarding_Screen_Flow</fullName>
    </flowDefinitions>
</Translations>

Querying Translated Custom Labels via Tooling API (ExternalStringLocalization)#

While the Translations metadata file bundles everything together in source control, Custom Label translations are stored at the database layer in the Tooling API object ExternalStringLocalization.

Query All Spanish and French Translations for a Specific Custom Label#

SELECT Id, ExternalStringId, ExternalString.Name, ExternalString.Value,
       Language, Value, LastModifiedDate
FROM ExternalStringLocalization
WHERE ExternalString.Name = 'Approval_Submitted_Toast_Message'
ORDER BY Language ASC

(Run this query against the Tooling API endpoint /services/data/v68.0/tooling/query/.)

Senior Architect Best Practices & Gotchas#

• Flow Version Number Independence: Starting in recent API versions, <flowDefinitions> inside Translations supports omitting the hardcoded version suffix (_1, _2) on <fullName> so translations carry forward cleanly when you activate a new version of a Screen Flow.

Frequently asked questions

What is the difference between Translations and CustomObjectTranslation?

CustomObjectTranslation localizes metadata tied to a specific object (fields, validation rules, record types), whereas Translations (stored in translations/lang.translation-meta.xml) localizes org-wide components like Custom Labels, Custom Tabs, Custom Applications, Flows, and Prompt Templates.

How do you deploy translated Custom Labels in SFDX?

Translated Custom Labels are stored inside force-app/main/default/translations/lang.translation-meta.xml under customLabels blocks containing the CustomLabel developer name and localized label.

Can Screen Flow labels and input prompts be translated via the Translations metadata type?

Yes. The flowDefinitions element inside a .translation-meta.xml file allows you to translate Flow definition labels, Screen field labels, help text, choice labels, and validation error messages across Flow versions.

What are the three tiers of language support in Salesforce Translation Workbench?

Salesforce categorizes languages into Fully Supported languages (full UI and Setup translation), End-User languages (standard objects and end-user pages translated, Setup remains English), and Platform-Only languages (you provide all translations via metadata).