Localize product property values
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Product names may be localized for different regions. With Microsoft Dynamics 365 (online & on-premises) you can provide localized labels for certain product attributes so that people will see the localized names that match their language preferences. This topic is about how developers can interact with this feature. For step-by-step instructions to use this feature in the application, see Help & Training: Translate product names and properties into multiple languages.
In this topic
Attributes that support localized property values
Retrieve localized property values
Query using localized values
Create or update records with localizable attributes
Translate localizable attributes
Uninstall a language
Attributes that support localized property values
The following list contains the attributes that support localizable values:
Product.Name
DynamicProperty.Name
DynamicPropertyOptionSetItem.DynamicPropertyOptionName
DynamicPropertyOptionSetItem.DynamicPropertyOptionDescription
The StringAttributeMetadata and MemoAttributeMetadata classes have a read-only IsLocalizable Boolean property that is false for all attributes except the four in the preceding table.
Retrieve localized property values
You don’t need to do anything differently to retrieve the localized value that matches the user’s language preference. If a localized value exists for the user’s preferred language, it will be returned. If a localized value doesn’t exist, the value for the organization’s base language will be returned. This behavior maintains backwards compatibility; any code you currently have using the product name attribute will continue to work using any localized values. If the localization of property values is incomplete, people may see mixed language values.
To retrieve all the localized labels for a specific localizable attribute, use the RetrieveLocLabelsRequest message.
Query using localized values
When you query entities with conditions using values for localized attributes, the conditions will be evaluated using your preferred language first and will revert to the base language if there is no localized value for that attribute. Query results for localized attribute values will be those for your preferred language if they exist. Otherwise, the results will use the base language values.
Create or update records with localizable attributes
Records with localized attributes are read-only unless your preferred language is the organization’s base language. You can only create records with localized property values using the organization’s base language. If you update the base language value for a localizable attribute any localized values for that attribute are not changed except if you clear the value for the base language. If you set the base language value to null or an empty string, all localized values for that property will also be cleared.
To add or update localized labels for any specific localized attribute, use the SetLocLabelsRequest message or import translated values. Any changes to the localizable attributes will appear in the audit history for the record. The language code identifier (LCID) for the localized value will appear in the audit history.
Translate localizable attributes
The process of localizing localizable attributes programmatically is similar to the process used to translate localized solution labels. More information: Translate customized entity and attribute text
Unlike translating metadata values, the user exporting and importing localized attributes values does not have to have the system administrator security role. The sales manager security role has the privileges necessary to translate localizable attributes. The person translating localized property values can only export those records they have access to view and update those records they have privileges to update.
To translate localizable attributes programmatically you must first export the current localized label definitions using ExportFieldTranslationRequest. The ExportFieldTranslationResponse.ExportTranslationFile property contains a byte[] for a compressed crmFieldTranslations.zip file containing a [Content_types].xml file and a crmFieldTranslations.xml file that can be opened using Microsoft Office Excel. The Localized Labels worksheet contains a column with an LCID value for each provisioned language for the organization. The column with the base language values will be populated and the columns for each provisioned language will contain any previously localized values. This file can be edited by a translator to provide localized labels for the localizable properties.
Tip
If you want to perform a bulk update of just the base language names, you can also edit the base language values.
After the crmFieldTranslations.xml file is edited to provide localized labels, compress it together with the [Content_types].xml file and set that file as the TranslationFile property of the ImportFieldTranslationRequest.
Modify the values included when exporting translated property values
The values that are included in the exported translations are controlled by customizable views associated with the entities that support localizable property values. Only the product entity displays this view in the customization user interface. These views are named Export Field Translations. The following table provides the SavedQueryId for these views.
Entity |
SavedQueryId |
Default FetchXml |
|---|---|---|
product |
9cfe2a9f-13c4-e311-8f2e-00155d9d2505 |
<fetch version="1.0" |
dynamicproperty |
4833cf48-1ac4-e311-8f2e-00155d9d2505 |
<fetch version="1.0" |
dynamicpropertyoptionsetitem |
d64cce30-1fc4-e311-8f2e-00155d9d2505 |
<fetch version="1.0" |
You can edit the FetchXml property of these views to filter out any attribute property values you do not want to include. For example, you may want to exclude archived records or only include those updated after a certain date.
Monitor the progress of field translation import jobs
The system job entity contains the following views to monitor the progress of field translation import jobs:
All Field Translation Import Jobs
Completed Field Translation Import Jobs
In Progress Field Translation Import Jobs
My Field Translation Import Jobs
Not Started Field Translation Import Jobs
The following conditions will cause errors when importing translation jobs:
Message |
Description |
|---|---|
Warning: You don’t have write permissions to one or more of the rows specified in the import file for worksheet {0}, Line {1}. |
The person running the import may not have write permissions to a row included in the imported file. Processing of other rows will continue. |
Warning: The base language translation string present in worksheet {0}, row {1}, column {2} is null. |
A base language value cannot be cleared by importing translations. Processing of other rows will continue |
Warning: The number of cells in row {0} don’t match the number of cells in row 1 in worksheet {1}. |
All rows in the spreadsheet must have the same number of cells. Processing of other rows will continue. |
Warning: An invalid Entity name was found in worksheet {0}, Line {1}, Column A. |
There is no valid entity in the system using a name in the worksheet. Processing of other rows will continue. |
Warning: An invalid Object Column Name was found in worksheet {0}, Line {1}, Column C. |
There is no valid localizable attribute in the system using a name in the worksheet. Processing of other rows will continue. |
Warning: An invalid Object Id was found in worksheet {0}, Line {1}, Column B. |
There is no matching record in the organization for item in this row. Processing of other rows will continue. |
Error: No rows were found in worksheet {0}. |
The worksheet to import is empty. |
Error: The Organization ID present in worksheet {0} does not match the current Organization ID. |
You can only import translations into the same organization they were exported from. |
Warning: An invalid language code was found in worksheet {0}, Column {1}. | Details: {2} |
The LCID in the column isn’t a valid integer or the Language pack for the language is not installed. The translations in the column are ignored. Valid locale ID values can be found at Locale ID (LCID) Chart. |
Error: A duplicate language code was found in worksheet {0}, Column {1}. |
Each column must have a different language code. |
Error: The translation file is invalid. The compressed file must contain the following files at its root: CrmFieldTranslations.xml, [Content_Types].xml |
The compressed (zip) file to be imported must contain only the files described in the error. |
Error: The translations file is invalid or doesn’t conform to the required schema. |
The CrmFieldTranslations.xml file included in the compressed (zip) file must be a file that was exported from the system and only edited to provide localized values. Other changes may invalidate the file. |
Uninstall a language
Any localized labels provided for a language that is uninstalled will remain in the system so that they’ll be in place if the language is reinstalled.
See Also
Product catalog entities
Translate customized entity and attribute text
Help & Training: Translate product names and properties into multiple languages
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright