Translations and multi language
## Translations & Multi-Language Support
Introduction
One of the key improvements of My-Scan 5, is that the translations are now dynamic. This means that they can be adjusted whenever this is needed, without the need for a developer. Currently, we only support dynamic translations for an enterprise device that is using distribution, but the solution is designed to be extendible for mobile devices as well. This page describes how to work with translations in the My-Scan 5 apps.
Configuring Translations
There are currently three levels of translations in the My-Scan 5 apps:
- Default translations, created when the app is build.
- Local stored translations, stored when retrieved from the distributed files, used when there are no new translations available.
- Distributed translations, always have the highest priority, and are stored locally, so they are still available if the file is no longer on the device.
In order to override the default translations, you can distribute a translation file for the appropriate language to the device. (For example: EN.json) The My-Scan 5 app will load these translations, and will use them from that moment. In order to use them after the file has been removed, it stores the translations locally. The My-Scan 5 app expects the translations to be in the following folder: /sdcard/mdc/selfscan/translation/{language_code}.json.
The fallback mechanism of the translations works as follows:
- Applications document directory/translations/
{language_code}.json. (The translations that the app has stored.) - /sdcard/mdc/selfscan/translations/
{language_code}.json. (The distributed file.) - App resources/
{language_code}.json. (The default translations in the app.) - The translation key. (If no translation has been found in the files above.)
It is always best practice to let development know that the translations have been changed. We can then include the new translations, and use them as the defaults. This ensures you don't have to distribute the file to every device in the future, when for example a new store will open. (And it ensure that when a bug is reported, development is seeing the same messages as the customer, and the other departments.)
Parameters
| Parameter Name | Default | Possible Values |
|---|---|---|
| SupportedLanguages | EN | All language codes, separated by a comma. |
| DefaultLanguage | EN | A value that's also configured in the supportedLanguages parameter |
Multi-Language Support
The My-Scan 5 apps can be released in any of the SupportedLanguages, and when not specified, they will be released in the DefaultLanguage. It is advised to have proper translations in the app for all supported languages, to ensure that the app can always fallback to sensible translations.
Logging
Default translations (translations in the app itself)
When the app is started the translations are loaded. In case there is no external translation file (so there are no overruling translations then this is also logged:
2023-02-06 12:18:01.102 - INFO - mdc_localizations - Loading translations for language "en"
2023-02-06 12:18:01.118 - INFO - mdc_localizations - Loaded translations from asset "lang/en.json"
2023-02-06 12:18:01.118 - INFO - mdc_localizations - Loaded translations for language "en"
2023-02-06 12:18:01.118 - FINE - mdc_localizations - No translations to overrule
When a translation key is missing in the default translations AND there is no external translation file or the translation key is also not present in the external translations file then this is visible on the screen (the translation keys are displayed instead of a proper translation) and it's also logged on WARNING level.
2023-02-10 06:58:03.313 - WARNING - mdc_localizations - No translation available for key ScreensaverContext.customerCardLabel
When this missing translation key is added to the external json file then this warning is not logged anymore.
Distributed / external translations (from /sdcard/mdc/<app>/translations/<language>.json)
When the external translation file is loaded, and this file is missing some translation keys that are NOT missing in the default translations this will be logged when the translation file is loaded (on FINE level). "Loaded default value for missing translation key", this means the default translation (from the app) is loaded since the translation key is missing in the external translations file.
2023-02-03 16:09:59.960 - INFO - Attendant - 2023-02-03 16:09:59.960 - INFO - Attendant - Dart runtime: 2.19.0 (stable) (Mon Jan 23 11:29:09 2023 -0800) on "android_arm64"
2023-02-03 16:09:59.960 - INFO - Attendant - Operating system: android, version: 11-27-14.00-RG-U01-STD-HEL-04
2023-02-03 16:09:59.961 - INFO - NativeLogger.Android - Initialized
2023-02-03 16:09:59.963 - INFO - Attendant - Application: Attendant, version: 2.26.1, build: 74, package: nl.revision.attendant
2023-02-03 16:09:59.966 - INFO - mdc_localizations - Loading translations for language "en"
2023-02-03 16:09:59.983 - INFO - mdc_localizations - Loaded translations from file "/sdcard/mdc/attendant/translations/en.json"
2023-02-03 16:09:59.985 - INFO - mdc_localizations - Loaded translations from asset "lang/en.json"
2023-02-03 16:09:59.985 - INFO - mdc_localizations - Loaded translations for language "en"
2023-02-03 16:10:00.030 - FINE - mdc_localizations - [warning] Loaded default value for missing translation key: AttendantContext.inactiveTerminalsTab
2023-02-03 16:10:00.031 - FINE - mdc_localizations - [warning] Loaded default value for missing translation key: AttendantContext.settingsTab