# Translate Document Content

## What You'll Learn

In this tutorial, you'll build a translated S-Docs template and test it end to end. By the end, you'll know how to:

* Translate regular field output with data translation maps
* Translate picklist values and field labels with Salesforce Translation Workbench
* Translate related list picklist values with `toLabel()`
* Configure template language settings correctly
* Generate a test document and verify the output

## What You'll Build

A template that can generate an Opportunity document in another language.

Your translated document can include:

* Regular field values translated with a data map
* Picklist values translated with Salesforce translations
* Field labels translated in the document body
* Related list picklist values translated in query output

**Estimated time:** 25 minutes

## Prerequisites

Before you start, make sure you have:

* Permission to edit S-Docs templates
* Permission to manage Salesforce translations
* An existing S-Docs template to test with
* A sample record with data you can translate
* Translation Workbench enabled in Salesforce

If you need to translate the S-Docs interface itself, see [Translating the S-Docs User Interface (UI)](https://github.com/kvantiem-sdocs/Quick-Start-Documentation/blob/main/advanced-template-logic/translations/translating-the-s-docs-user-interface-ui.md).

{% stepper %}
{% step %}
**Step 1: Choose a Template and a Target Language**

Open the template you want to translate.

For this tutorial, use one target language such as French, German, or Spanish.

Pick a few values you want to translate first:

* A regular text or formula field value
* A picklist field value
* A field label
* A picklist field inside a related list

Keeping the first test small makes troubleshooting much easier.
{% endstep %}

{% step %}
**Step 2: Create a Data Translation Map**

Use a data translation map for regular field output that does not come from Salesforce picklist translations.

1. Open the App Launcher.
2. Search for **S-Docs Setup**.
3. Open **S-Docs Setup**.
4. Scroll to **Translate Data/UI**.
5. Click **Go To S-Docs Translation Page**.
6. Enter your language name, such as `French`.
7. Click **Define new translations for this language**.
8. In **Data Translations**, click **Add New Section**.
9. Enter a section name such as `Opportunity Values`.
10. Click **Add New Field**.
11. Enter the original value.
12. Enter the translated value.
13. Repeat for each value you need.
14. Click **Save**.

Example map:

* `North Region` → `Région Nord`
* `Renewal Pending` → `Renouvellement en attente`
* `Executive Review` → `Examen de direction`

{% hint style="info" %}
When you save a new language, S-Docs creates translation template records automatically. Do not edit those records directly.
{% endhint %}
{% endstep %}

{% step %}
**Step 3: Add Data Map Translation to Merge Fields**

Add the `translate="data-map"` attribute to merge fields that should use your data map.

Example:

```html
{{!Opportunity.Region_Text__c translate="data-map"}}
```

Use this on fields whose output exactly matches a value in your translation map.

If the source value is not in the map, S-Docs will output the original value.
{% endstep %}

{% step %}
**Step 4: Set the Template Data Language**

Your template must point to the same language name you created on the translation page.

1. Open your S-Docs template record.
2. Find the **Data Language** field.
3. Enter the exact language name you created earlier.
4. Save the template.

If your language name is `French`, the template must also use `French`.

This value must match exactly.
{% endstep %}

{% step %}
**Step 5: Add Salesforce Translation Workbench Translations**

Use Translation Workbench for picklist values and field labels.

From Salesforce Setup:

1. Search for **Translate**.
2. Open **Translate**.
3. Set **Language** to your target language.

To translate a picklist value:

1. Set **Setup Component** to **Picklist Value**.
2. Select the object.
3. Find the field.
4. Enter the translated picklist values.
5. Save.

To translate a field label:

1. Set **Setup Component** to **Custom Field**.
2. Set **Aspect** to **Field Label**.
3. Enter the translated label.
4. Save.

Standard Salesforce field labels usually already include Salesforce translations. Custom field labels usually need manual translation.
{% endstep %}

{% step %}
**Step 6: Enable Template Language for Translation Workbench**

Templates need a Salesforce language code when you want Translation Workbench output in generated documents.

1. In Setup, open **Object Manager**.
2. Open **SDoc Template**.
3. Open **Page Layouts**.
4. Edit your template layout.
5. Add the **Language** field to the template detail section.
6. Save the layout.
7. Open **Fields & Relationships**.
8. Open the **Language** field.
9. Add the language code you need, such as `FR`, `DE`, or `ES`.

After that, go back to the template record and select the language code.

Use `FR` for French, `DE` for German, or the code that matches your Salesforce translation language.
{% endstep %}

{% step %}
**Step 7: Add Translation Workbench Attributes to Merge Fields**

Add `translate="true"` to picklist merge fields and field label merge fields.

For a picklist field value:

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

For a field label:

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

Use this method for values Salesforce already knows how to translate.

{% hint style="info" %}
Use data maps for regular text values. Use Translation Workbench for picklists and labels.
{% endhint %}
{% endstep %}

{% step %}
**Step 8: Translate Related List Picklist Values with `toLabel()`**

If a related list query returns a picklist value, add `toLabel()` in the SOQL query.

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 tells Salesforce to return the translated label for that picklist field.

Keep the column name aligned with the selected field.

If you need raw query output without table formatting, use `class` set to `none`.
{% endstep %}

{% step %}
**Step 9: Handle Unicode or Right-to-Left Output**

If your translated template includes languages such as Japanese, Arabic, or Hebrew, enable Unicode support.

1. Open the template.
2. Go to **Document Options**.
3. Enable **Template contains international characters (Unicode fonts)**.
4. If needed, set **Unicode Enforcement Level** to **Strict**.

For right-to-left merge field output:

```html
{{!Account.Name rtl="true"}}
```

For right-to-left static text and merge fields together:

```html
<rtl>مرحبا {{!Account.Name}}</rtl>
```

If you work with right-to-left languages often, see [How to Work with Right-to-Left Languages](https://github.com/kvantiem-sdocs/Quick-Start-Documentation/blob/main/advanced-template-logic/template-attributes/template-attributes-how-to-guides/how-to-work-with-right-to-left-languages.md).
{% endstep %}

{% step %}
**Step 10: Generate a Test Document**

Now test the full flow.

1. Open a record that matches your template.
2. Generate the document.
3. Verify each translation type:
   * Data map fields show translated values
   * Picklist fields show translated labels
   * Field labels display in the target language
   * Related list picklists display translated labels
4. Compare the output with the original Salesforce data.

If one translation type fails, test that part separately before changing the rest of the template.
{% endstep %}

{% step %}
**Step 11: Fix Common Issues**

Use this checklist when translations do not appear.

**Data map fields stay in English**

* Confirm the template **Data Language** exactly matches the defined language name
* Confirm the output value exactly matches a value in the data map
* Confirm the merge field includes `translate="data-map"`

**Picklist values do not translate**

* Confirm Translation Workbench has a translation for that picklist value
* Confirm the template **Language** field is set to the correct Salesforce language code
* Confirm the merge field includes `translate="true"`

**Field labels do not translate**

* Confirm the label is available in Salesforce translations
* Confirm custom field labels were translated manually
* Confirm the label merge field includes `translate="true"`

**Related list values do not translate**

* Confirm the field is a picklist
* Confirm the query uses `toLabel(FieldName)`
* Confirm the template language code matches the translation language
  {% endstep %}
  {% endstepper %}

## What You've Learned

You now know how to combine both S-Docs and Salesforce translation features in one template.

You can now:

* Translate regular field output with data maps
* Translate picklist values and field labels with Translation Workbench
* Translate related list picklists with `toLabel()`
* Support Unicode and right-to-left output when needed

## Next Steps

For deeper reference material, see:

* [Setup Translations](https://github.com/kvantiem-sdocs/Quick-Start-Documentation/blob/main/advanced-template-logic/translations/README.md)
* [Translating Document Content in S-Docs](https://github.com/kvantiem-sdocs/Quick-Start-Documentation/blob/main/advanced-template-logic/translations/translating-document-content-in-s-docs.md)
* [How to Translate Merge Fields and Field Labels](https://github.com/kvantiem-sdocs/Quick-Start-Documentation/blob/main/advanced-template-logic/translations/how-to-translate-merge-fields-and-field-labels.md)
* [How to Create Multilingual Documents](https://github.com/kvantiem-sdocs/Quick-Start-Documentation/blob/main/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/quick-start/template-building/document-content-translation-tutorial.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.