Salesforce SOQL toLabel() Function

In Salesforce SOQL, we use the toLabel() function in the queries to retrieve translated field labels in multi-language Salesforce orgs. This means it translates SOQL query results into the user’s language, which submits the query using the toLabel function.

In this Salesforce tutorial, I will explain the toLabel() function in Salesforce and its use cases for executing SOQL queries in various scenarios.

Table of Contents

What is the toLabel() function in Salesforce SOQL?

In Salesforce SOQL, the toLabel() function is used to translate the data from a field in the user’s locale language. It converts the results into the user’s language if the translation workbench is enabled.

The toLabel() function is available in all editions of Salesforce, and using this, we can translate the values of supported fields, including Picklist, Lookup, and standard fields, with translations.

Syntax to use the toLabel() function in Salesforce SOQL:

The basic syntax to execute the toLabel() function in Salesforce SOQL is as follows:

SELECT toLabel(<field name>) FROM <object name>

For example, you have to query the Picklist value Rating in your org language from the custom object Product_c. Then the query will be executed as follows.

SELECT toLabel(Rating__c) FROM Order_c

After executing the query, the returned records will be translated into the language of the user who issued the query.

If the translation settings are not enabled, then you might not get the translated values in the SOQL queries.

To enable the translation language settings, follow the steps below.

On the setup page, search for and select Translation Language Settings.
In the language setup, click on the Add button, select the Language, and select the Active checkbox.
In the section Identify Translators for this Language, select the users and click the Save button.

Now, the enabled language will be available for the selected users.

Use the toLabel() function to translate Picklist values in Salesforce SOQL

In Salesforce SOQL queries, we can use the toLabel() function to filter records using a translated picklist value from any standard or custom Salesforce object.

For example, we have to filter records using the picklist value “Is draft“, which is translated in German as “ist Entwurf“. Then, the SOQL will be executed as the below query.

SELECT Company, toLabel(Status)
FROM Lead
WHERE toLabel(Status) = 'ist Entwurf'

The query returns lead records with a picklist value for Status equal to ‘ist Entwurf.’ The comparison is made against the value of the user’s language. If no translation is available for the picklist, the comparison will be made against the master values.

There are some limitations to translating the picklist values using the toLabel() function.

The LIKE operator can only query on the label of the picklist, not on its API name.
We can’t use the toLabel() function with the operator ORDER BY. SOQL always uses the picklist’s defined order.
We can’t use the toLabel()function for division or currency ISO code picklists in a WHERE clause.

Using toLabel() function with the Lookup field in SOQL

The toLabel() function can also be used to fetch the translated names of Lookup field values, and for that, we can execute the SOQL query in the following way.

To query the translated names from the account of records, we can execute the query in the following way.

SELECT Name, toLabel(Account.Name)
FROM Contact
WHERE Account.Industry = 'Technology'

This will return the name of the related Account, converted into the user’s localized language using the toLabel() function.

Use toLabel() function for Multiple fields in Salesforce SOQL

We can also use the toLabel() function to get the translated values of multiple fields in Salesforce SOQL queries.

For example, if you want to get the translated field status and priority values from the Case object, then the SOQL query can be executed as follows.

SELECT toLabel(Status), toLabel(Priority), Subject 
FROM Case
WHERE Priority = 'High'

Output:

This way, we can use the toLabel() function for multiple fields to get their values according to the user’s locale language settings.

Considerations and Limitations while using toLabel() function in SOQL

Below are considerations and limitations to users of the toLabel() function in Salesforce SOQL queries.

Considerations:

This function is useful when multiple languages are enabled in your org. It ensures that field values like picklist values or record type names appear in the user’s language settings.
This function supports translation in SOQL for fields such as picklist values, record types, and custom field translations. It does not apply to fields like Text or Text Area.
If a translation is unavailable for a particular field value, it defaults to the value stored in the org’s base language.

Limitations:

The toLabel() function is not supported by WHERE and ORDER BY clause in a SOQL query.

For example, the following query will be considered invalid.

SELECT Id FROM Case WHERE toLabel(Status) = 'Open'

This function supports only those fields whose values can be translated, like it supports standard and custom picklist fields, but not the text fields.
When you export the query result for external use, the translated values retrieved via toLabel may not align as expected if the language settings differ.

Conclusion

In this Salesforce tutorial, we have learned about the value language translation function toLabel(), using which we can translate the values in SOQL queries according to the user’s language settings.

Along with this, we also discussed the Limitations and Considerations that we should be aware of while using the toLabel() function in the SOQL queries.