Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Product names can be localized for different regions. By using Dynamics 365 Sales, you can provide localized labels for certain product attributes so that people see the localized names that match their language preferences. This article explains how developers can interact with this feature. For step-by-step instructions to use this feature in the application, see the previous versions documentation on Translate product names and properties into multiple languages.
Attributes that support localized property values
The following list contains the attributes that support localizable values:
Product.NameDynamicProperty.NameDynamicPropertyOptionSetItem.DynamicPropertyOptionNameDynamicPropertyOptionSetItem.DynamicPropertyOptionDescriptionThe StringAttributeMetadata and MemoAttributeMetadata classes have a read-only
IsLocalizableBoolean property that isfalsefor 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, the system returns it. If a localized value doesn't exist, the system returns the value for the organization's base language. This behavior maintains backward compatibility; any code that currently uses the product name attribute continues to work by using any localized values. If the localization of property values is incomplete, users might see mixed language values.
To retrieve all the localized labels for a specific localizable attribute, use the RetrieveLocLabelsRequest message.
Query by using localized values
When you query tables by using values for localized attributes in conditions, the system evaluates the conditions by using your preferred language first. If there are no localized values for the attribute, the query reverts to the base language. The query results for localized attribute values are returned in your preferred language if they exist. Otherwise, the results are returned in your base language.
Create or update records with localizable attributes
Records with localizable attributes are read-only unless your preferred language is the organization's base language. You can only create records with localized property values by using the organization's base language. If you update the base language value for a localizable attribute, the localized values for that attribute don't change, 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 are also cleared.
To add or update localized labels for any specific localizable attribute, use the SetLocLabelsRequest message or import translated values. Any changes to the localizable attributes appear in the audit history for the record. The language code identifier (LCID) for the localized value appears 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. [!INCLUDE[proc_more_information]Translate customized table and column text
Unlike translating metadata values, the user exporting and importing localized attribute values doesn't need 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 by 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 by using 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 is populated and the columns for each provisioned language contain any previously localized values. A translator can edit this file 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 you edit the crmFieldTranslations.xml file 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
Customizable views associated with the tables that support localizable property values control the values that are included in the exported translations. Only the product tables display this view in the customization user interface. These views are named Export Field Translations. The following table provides the SavedQueryId for these views.
| Table | SavedQueryId |
Default FetchXml |
|---|---|---|
| product | 9cfe2a9f-13c4-e311-8f2e-00155d9d2505 | <fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false"> <entity name="product"> <attribute name="name" /> </entity> </fetch> |
| dynamicproperty | 4833cf48-1ac4-e311-8f2e-00155d9d2505 | <fetch version="1.0" output-format="xml-platform" mapping="logical"> <entity name="dynamicproperty"> <attribute name="name" /> </entity> </fetch> |
| dynamicpropertyoptionsetitem | d64cce30-1fc4-e311-8f2e-00155d9d2505 | <fetch version="1.0" output-format="xml-platform" mapping="logical"> <entity name="dynamicpropertyoptionsetitem"> <attribute name="dynamicpropertyoptionname" /> <attribute name="dynamicpropertyoptiondescription" /> </entity> </fetch> |
You can edit the FetchXml property of these views to filter out any attribute property values you don't want to include. For example, you might want to exclude archived records or only include those records updated after a certain date.
Monitor the progress of field translation import jobs
The system job tables include 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 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 might not have write permissions to a row included in the imported file. Processing of other rows continues. |
| Warning: The base language translation strings present in worksheet {0}, row {1}, column {2} is null. | You can't clear a base language value by importing translations. Processing of other rows continues. |
| 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 continues. |
| Warning: An invalid Table name was found in worksheet {0}, Line {1}, Column A. | There's no valid table in the system using a name in the worksheet. Processing of other rows continues. |
| Warning: An invalid Object Column Name was found in worksheet {0}, Line {1}, Column C. | There's no valid localizable attribute in the system using a name in the worksheet. Processing of other rows continues. |
| Warning: An invalid Object ID was found in worksheet {0}, Line {1}, Column B. | There's no matching record in the organization for item in this row. Processing of other rows continues. |
| Error: No rows were found in worksheet {0}. | The worksheet to import is empty. |
| Error: The Organization ID present in worksheet {0} doesn't 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 isn't 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 import 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 can invalidate the file. |
Uninstall a language
The system keeps any localized labels for a language you uninstall. If you reinstall the language, the labels are already in place.
Related information
Product catalog tables
Translate customized table and column text
Translate product names and properties into multiple languages