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:

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:

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:

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[2].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:

French-1.45.lng
French-1.46.lng
French-1.49.lng

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:

French-1.49.lng
French-1.49[2].lng

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 1.5.0.0, but in the translations folder we have only the below files:

French-1.37.0.0.lng
French-1.38.0.0.lng
French-1.39.0.0.lng

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.


See also: