How to use product translations in DoumentsCorePack templates

Microsoft Dynamics 365 allows to define translations for product properties like product name or product description as can be seen in this article. By default, DocumentsCorePack will load the language defined by the user that is generating the doucment. This article describes how to set the language to be loaded into a certain template.

Use Case: Let’s assume your office is in England and your users are all using Dynamics 365 in english but you have customers out of Germany you need to send German documents that should show the German names of the products accordingly.

Product translations are stored in the so called “Business Data Localized Label“-table. This entity is only loosely bound to the product entity and the fields within do not have Display Names. Therefore you will need to perform the following steps to retrieve fields in the desired language:

1. Enable support for fields without Display Name

First, we need to enable our Template Designer within Microsoft Word to work with fields that do not have a Display Name defined. This can be done by

1. Opening the “Insert MailMerge Fields“-taskbar
2. Open the treeview settings
3. Enable the “Add fields without DisplayName” option and hit OK

2. Add relationship to your template

Typically you will need product translations to be available for products. Thus, we would recommend to resolve the relationship to products (e.g. Quote ⇒ Quote Detail ⇒ Product) using our relationship designer.

Since the translation is only loosely bound we cannot use our relationship designer but will need to add the fetch-statement that retrieves translations to our query manually. To do so, please open the relationship in edit mode.

1. Select the “Additional“-tab
2. Select the relationship to the product entity you want to add translations to
3. Press the “Edit” button
4. Switch to the “FetchXML” Tab

Now to the most important part: Adding the relationship to deliver translated content in the preferred language.
The fetch-to be added looks as follows:

<link-entity name='businessdatalocalizedlabel' from='objectid' to='productid' alias='productid_businessdatalocalizedlabel'>
	<attribute name='languageid' />
	<attribute name='label' />
	<attribute name='objectcolumnname' />
	<attribute name='businessdatalocalizedlabelid' />
	<filter type='and'>
		<condition attribute='objectidtypecode' operator='eq' value='1024' />
		<condition attribute='objectcolumnname' operator='eq' value='name' />
		<condition attribute='languageid' operator='eq' value='1031' />
	</filter>
</link-entity>

IMPORTANT: The language-id specified in the following line defines the language to be retrieved. You can find the codes in Dynamics 365 ⇒ Advanced Settings ⇒ Administration ⇒ Languages

<condition attribute='languageid' operator='eq' value='1031' />

In our case we choose to load 1031 (German).

We recommend to copy the above fetch statement, set the language-id as needed and add it to your fetch from the predefined relationship. In our case this looks as follows:

Hit Ok. A new node “Business Data Localized Label” will now be visible in your tree.

3. Add field to your template

The field that will now deliver the product name in the correct language is called “*label“. You can go ahead and ad this field to your document as needed.

You will also find a working demo-template that has the relationship included attached to this document.