Requirements and Key Aspects
Adding the Library to your Project
The LangsHelper library is supplied as 32- and 64-bit Windows DLLs. The header files are supplied for C++ and Object Pascal, so the library can be used with many compilers/IDEs including Visual C++, Clang, MinGW, Delphi, CLion, Qt Creator and C++ Builder.
To add the library to your application, you need to put the LangsHelper.32.dll or LangsHelper.64.dll file to the same folder with your project's executable. It can be found in the Bin\Release folder.
Also you need to include to your project:
- For C++: The file Cpp\Include\LangsHelper.h. Also it depends on the stuff from the folder Cpp\Include\supplemental.
No need to add any lib-files to your project, just #include "LangsHelper.h" and you may use the library's classes.
- For Delphi: The file Delphi\Source\LangsHelper.pas. Also it depends on the file LHLowApi.pas in the same folder.
Requirements to the Application
In order to integrate LangsHelper with your application, the latter must be able to load the translation from the external file. Such files must be located in a single folder anywhere on the computer where the application is installed. The names of the translation files must match the format described below. The typical names of the translation files are: English.lng, French.xml, Russian.bin (or whatever other extension that is used in your app).
Any number of the translations may be pre-built into your app and not have separate files. It will not be a problem to support them in LangsHelper.
The translation files must have an extension, but it can be anything.
Official and Unofficial Translations
In the domain model, there are 2 kinds of the translations which can be used with your app:
Official. These translations are supplied by the application’s developer and are installed along with the application once the user has installed it. If the official translation is stored in an external file, the latter should be named using this format:
- Language (required part) - the name of the language in the terminology of Windows, in English. This is the name returned by the GetUserDefaultLocaleName WinAPI function. The language name of the current system can be obtained by calling the LangHelper’s static function named TMiscFunctions::GetSystemLanguage().
- Extension (required part) – the file extension. Any non-empty extension can be used.
Examples: English.lng, French.xml, Russian.bin.
Unofficial. Unofficial translations are downloaded from the server to which the translators submit them. Such translations are associated with the specific version of the application. They should be named as below:
<Language>-<App version>>([Translation version]).<Extension>
- Language, Extension – has the same meaning as above.
- App version – version for which this translation is made.
- «[» and «]» are literal characters.
Examples: French-22.214.171.124.lng, French-1.50.xml, Russian-3.40 beta 5.bin.
The official translation always has the priority over the unofficial one for the same language. This means that if the application has a translation file named English.lng (which is the official translation’s file) and English-1.15.lng (which is the unofficial one) the first translation will be used.
If you supply your application with the pre-installed language files, please consider the below two scenarios and choose which one to use:
- If you supply your application with the pre-defined language files, which you are always updating before releasing the new version, then name them as official translations (without versioning), for example, English.lng. In this case, they will be always used for the appropriate languages, and the library will not look for the better variants of the translations for these languages on the server.
- If you have released the version 1.5, but have a French language file only for version 1.45, then you may not pre-install that file at all, but put in on the server instead. In this case, it will be downloaded and applied only for French users. Nevertheless, if you still want to pre-install this file, feel free to do this, but name it as an unofficial translation, i.e.: French-1.45.lng. In this case, this language file will be used on the French system, but if the translation to version 1.50 appears on the server (in your LangsHelper account), it will be automatically download and applied for all French users, replacing the 1.45 translation.
Please note that in the last scenario, even if you named the pre-installed translation French-1.50.lng, you may, if necessary, update it on the user’s systems with the newer version via the server. To do this, you need to add to your LangsHelper account the new French translation and give it the bigger translation version (but not the target app’s version).
If the translation has the name French-1.50.lng then its translation version is 1. If you add to the server the file French-1.50.lng, it will (in the background) replace that translation on the French users’ systems as the latter translation has a bigger version number – 2.
Adding the translation can be easily done by the site; you will just need to specify the version. The name of the file will be picked automatically according to the domain model.
How the Library Chooses the Language File
When the library needs to pick the best language file for the specific language, it looks for the official translations to that language first. If such have been found, it will be used regardless of what unofficial translations are available for your application.
However, if the official translation is absent, the library will try to choose the more suitable unofficial one.
When the library decides which file of the unofficial translation to use, it calculates how close a program version is (which the translation file is targeted to) to the current application's version.
For example, if the program’s version is 1.5 and we have the below files in the folder:
If the library is choosing the most suitable translation file to French, it will pick French-1.49.lng.
If there are only the below files:
It will pick the second one, because it has the biggest translation’s version (2), rather than the other one (1).
There is a rule: The library uses only the unofficial translation for which the target version is different from the current application’s version to no more than 10 units in the second register. This means, that if the program’s version is 126.96.36.199, but in the translations folder we have only the below files:
then none of them will be used, and the library will consider that no translation to French is available for the application at the present time. This rule prohibits the use of outdated translations, because the program’s interface may have undergo the significant changes and the older language files may be displayed incorrectly. In such a case, the default translation will be used instead of the French translation.