Jump to Section
Synchronizing dictionary entries in a multilingual website
We are currently working on multilingual content for our website. We introduced entries in the dictionary based on the design and started preparing translations.
Of course, we create new entries in our local environment, and then we synchronize them with other environments using uSync.
However, sometimes we would like to improve existing translations directly on production. We don't want our modifications to be overridden during the upcoming synchronization executed in the uSync dashboard.
Therefore, we would like to utilize the CreateOnly option available in the DictionaryHandler settings, which is responsible for synchronizing the dictionary in Umbraco CMS.
You may also want to configure the dictionary handler so it only syncs new entries and leaves existing items that your users might have entered alone, you can configure the handler to be 'CreateOnly' so it will only sync new items
Unexpected overriding of translations in the dictionary
This option seems to be very useful and makes sense in most projects. Unfortunately, we have encountered an issue because some of our entries have been overridden during synchronization.
Of course, we run the report, review changes, and then import them, so we were aware that uSync was going to override our translations. However, we were forced to run synchronization immediately after the release, so we sacrificed the improved translation that was applied directly to production.
Please note that we perform synchronization manually, thanks to the disabled exporting at startup, as we want to be fully aware of the changes being applied to the environment.
However, in some projects, we have noticed that uSync imports changes immediately after the application starts. Let's leave aside whether this is a good or bad practice. Unfortunately, in this configuration, developers are not fully aware of the changes that will be applied during synchronization performed by uSync. Therefore, they can not be aware that uSync can override translations prepared by Umbraco editors.
Investigation
We decided to conduct an investigation to determine what was wrong.
First of all, we confirmed that we have the latest uSync version installed. Please note that the newest version available today is 13.3.2.
Secondly, we verified our uSync configuration several times.
Furthermore, we reviewed documentation once again and confirmed that our expectations regarding the possibility of uSync are not misunderstood or that we didn't make any typos.
Finally, we performed some tests and we confirmed that uSync is not respecting the CreateOnly option, which is set to true in our project.
Our steps to reproduce
- Run the report in the uSync dashboard to confirm that there is nothing to synchronize.
- Change translation for any existing entry in the dictionary.
- Ensure that uSync modifies the corresponding configuration file regarding the updated entry in the dictionary.
- Discard changes in the modified configuration file.
- Run the report in the uSync dashboard once again.
- Pay attention that uSync would like to synchronize the modified entry in the dictionary.
- Synchronize changes.
- Go to the modified entry in the dictionary.
- Check out the translation, which has been reverted to the previous state.
By discarding changes in the modified configuration file, we simulate the deployment process, which restores the configuration file to the state tracked by the repository.
Wrong uSync configuration
Our uSync configuration looks as below. As you can see, we synchronize translations together with other settings. I mean that we reassigned the DictionaryHandler to the Settings group, because dictionary entries are synced together with content by default.
In our case, we would like to have the Settings group only and import crucial changes at once.
"uSync": {
"Settings": {
"RootFolder": "uSync/v13/",
"DefaultSet": "Default",
"ImportAtStartup": "None",
"ExportAtStartup": "None",
"ExportOnSave": "Settings",
"UiEnabledGroups": "Settings",
"ReportDebug": false,
"AddOnPing": true,
"FailOnMissingParent": false,
"CacheFolderKeys": true,
"ShowVersionCheckWarning": true,
"CustomMappings": {},
"EnableHistory": true
},
"Sets": {
"Default": {
"Enabled": true,
"HandlerGroups": [],
"DisabledHandlers": [ "LanguageHandler" ],
"HandlerDefaults": {
"Enabled": true,
"Actions": [],
"UseFlatStructure": true,
"GuidNames": true,
"FailOnMissingParent": false,
"Group": "",
"Settings": {}
},
"Handlers": {
"DictionaryHandler": {
"Group": "Settings",
"CreateOnly": true
}
}
}
}
}By default, the DictionaryHandler is treated as a content handler, so Dictionary items are synced when you sync content.
It may be that you want your Dictionary items to be synced as settings, and this can be achieved by changing the group to which the DictionaryHandler is assigned.
Conclusion
Unfortunately, we were close to raising a new issue for uSync on GitHub regarding the translations overriding.
However, after numerous checks, we have realized that we made a mistake during the configuration of our website.
Basically, we included the CreateOnly option directly in the DictionaryHandler instead of the additional, nested Settings sections.
Just to clarify, there is nothing wrong and nothing to report regarding uSync and the DictionaryHandler. It was just our mistake. We have set the CreateOnly option in the wrong place.
Now, we are only wondering whether this option should be enabled by default.
Expected result
Below, you can see the expected result that should appear once the CreateOnly option takes action. I mean the orange caption, which is being displayed once a report is triggered.
One or more handlers are set to create only. [DictionaryHandler]. Changes within items may not be synchronized
As you can see, uSync is still informing about changes in the dictionary, but happily it's not applying them once the Import is being triggered.
Therefore, we are wondering if it should display possible updates or not once the CreateOnly option is set to true.