# How to: Translate Merge Fields and Field Labels

Use this guide when you need to translate picklist merge fields, field labels, or related list picklist values.

### When to use each method

Use the method that matches the value source.

* Use `translate="true"` for Salesforce-translated picklists and labels.
* Use `toLabel()` for picklist values returned by direct SOQL related lists.

{% hint style="info" %}
Use Translation Workbench when Salesforce already owns the translated label or picklist value.
{% endhint %}

### Translate picklist merge fields with Translation Workbench

Use this when the field is a Salesforce picklist and the translated value exists in Translation Workbench.

#### Example

```html
{{!Opportunity.StageName translate="true"}}
```

S-Docs will return the translated picklist label for the template language.

#### You also need

* Translation Workbench enabled in Salesforce
* The picklist value translated in Salesforce
* The template **Language** field set to the correct Salesforce language code

Use this method for Salesforce-managed translations, not custom free-text values.

### Translate field labels

Use label merge fields when you want the field name itself translated in the output.

#### Example

```html
{{!Label.Opportunity.StageName translate="true"}}
```

This returns the translated field label, not the field value.

Use this for headings, form labels, and side-by-side record summaries.

#### Label rules

* Standard field labels usually already have Salesforce translations.
* Custom field labels usually need manual translation in Translation Workbench.
* The template **Language** field must match the Salesforce translation language.

### Translate related list picklist values

If a direct SOQL related list returns a picklist field, wrap it with `toLabel()`.

#### Example

```html
<!--{{!
<lineitemssoql>
<class>table873</class>
<soql>SELECT Product2.Name, toLabel(Color__c) FROM OpportunityLineItem WHERE OpportunityId='{{!Opportunity.Id}}'</soql>
<column>rownum</column>
<column>Product2.Name</column>
<column>Color__c</column>
</lineitemssoql>
}}-->
```

This returns the translated picklist label for the current template language.

### Choose the right pattern fast

* Translating a picklist value: `translate="true"`
* Translating a field label: `{{!Label.Object.Field translate="true"}}`
* Translating a SOQL related list picklist: `toLabel(FieldName)`

### Common mistakes

#### `translate="true"` does nothing

Check these first:

* The field is not a picklist
* Translation Workbench does not have the translated value
* The template **Language** field is blank or wrong

#### Labels stay in English

Check these first:

* The custom field label was never translated in Salesforce
* The template **Language** field does not match the language code
* You used a field merge field instead of a label merge field

### Related guides

* [Set Up Translations](/sdocs/advanced-template-logic/translations.md)
* [Tutorial: Translate Document Content](broken://spaces/WKNnJmhJBQwhdk5WBFsi/pages/eDuxlkQ4qy9j6eR5s5js)
* [Reference: Translate Document Content](/sdocs/advanced-template-logic/translations/translating-document-content-in-s-docs.md)
* [How to Create Multilingual Documents](/sdocs/advanced-template-logic/template-attributes/template-attributes-how-to-guides/how-to-create-multilingual-documents.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.sdocs.com/sdocs/advanced-template-logic/translations/translating-document-content-in-s-docs/how-to-translate-merge-fields-and-field-labels.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.