Translator
In addition to working with locations, Jet must of course have a mechanism for translating text. More precisely, for collecting texts, placing them in dictionaries and preparing them for subsequent translation into the target language, more precisely the target localization.
Let's show you a practical application:
$error = Tr::_(
'Something went wrong: %error%',
[
'error' => $e->getMessage()
],
Tr::COMMON_DICTIONARY
);
And let's just say that the Jet\Tr class is a child of the Jet\Translator class and the _ method calls the getTranslation method. Of course, you would then need to use the following in your code:
echo Translator::getTranslation('Hello world!');
You can use the compiler this way too, but it's still too verbose. So in the source code of the sample application you will find rather this:
echo Tr::_('Hello world!');
Translator and localization
The translation must of course be tied to a specific localization. However, the compiler does not rely on the locale settings within the Jet\Locale class, but keeps its own settings for the current locale. Why is this? Theoretically, there may be situations where different data (numbers, dates, etc.) may need to be formatted according to different rules - a different localization than the one that will be relevant to the compiler. This will probably not be a common situation, but it is necessary that such a situation be resolvable.
For this reason, the Jet\Translator class has setCurrentLocale and getCurrentLocale methods.
If the application is built on Jet MVC, then the router sets the compiler localization automatically according to the detected base.
Dictionaries translators
Of course, all translations of the whole application cannot be on one heap (unless it is a microapplication). Translations are by default divided into dictionaries.
Besides the fact that the dictionary is of course linked to the localization, it has a name.
The name of the current dictionary can be handled by the setCurrentDictionary and getCurrentDictionary methods of the Jet\Translator class.
In addition, it is possible to use the dictionary name as an optional parameter of the $dictionary methods getTranslation and _. This makes it possible to perform a partial translation using a specific dictionary regardless of the current dictionary set.
The Jet\Translator class contains the COMMON_DICTIONARY constant. This constant is supposed to represent the name of a generic dictionary. A generic dictionary is a dictionary that is supposed to contain generic phrases ("Yes", "No", "Save", and so on) that will be common to all dictionaries; conversely, it would be counterproductive to place such repetitive and identical phrases in different dictionaries.
How dictionary storage is implemented is a matter of the backend, specifically the default backend, unless you develop your own backend.
The dictionary itself is represented by the Jet\Translator_Dictionary and Jet\Translator_Dictionary_Phrase classes.
An application built on Jet MVC behaves in such a way that when serving content provided by a particular application module, the dictionary name is automatically set to the same value as the name of the current application module.
Adding phrases to verbs
Once you're familiar with how backend stores dictionaries, then of course you can (and should) manually interfere with dictionaries. Add phrases, or delete phrases no longer in use, and most importantly, create translations.
Of course, adding phrases during development would be a pretty annoying job. That's why the system works by automatically adding newly found phrases to relevant dictionaries. So you use a new phrase in the source code of your application and it is automatically added - of course without translation yet.
This function is only active if the SysConf_Jet_Translator::getAutoAppendUnknownPhrase() setting allows it.
Recommendations when working with dictionaries and translations
- SlThe list should definitely be created during the development phase and especially during the testing phase of the application. The fact that there is nothing missing in the dictionary (including error messages) is actually one of the good indications that the application has been fully tested.
- Completed dictionaries (complete and translated) should be uploaded to the production environment.
- For these reasons, the automatic addition of phrases to dictionaries should be disabled on the production environment, and the dictionary files and directory should be unwritable on the production environment - read-only.
I also recommend you to get familiar with the Jet\Translator class in general and I also highly recommend you to see how the default backend works - so you can learn where and how the dictionaries are stored.