Technology Overview
The package introduces two non-visual VCL/Firemonkey components:
- TDKLanguageController
- TDKLTranslationsStorage
TDKLanguageController is placed on each form you wish to localize. The language controller automatically maintains an internal list of all components and their properties of type String or TStrings. There's little chance you will ever need another type of data to be changed in synch with language change.
So, the language controller keeps a list of component properties, each having assigned a form-wide unique natural number identifier (ID). This is done transparently by the controller so you don't need to bother when you add or remove components to/from the form, or change their property values.
Additionally, if a controller's Options include dklcoAutoSaveLangSource (this is the default), the controller saves its data in a plain text file into the project language source, each time you save modifications to the form the controller is on. The project language source is a file named the same as the project (.dpr) file, but having .dklang extension. Each controller replaces the corresponding section in that file when it saves its data. If autosave is off you are still able to save the controller data by right-clicking the component on the form and selecting the Save data to project language source item. You may also select the Project | Update project language source main menu item, this will force all the contollers available for the project to update their language source in project's .dklang file.
TDKLTranslationsStorage is used to store translations in a compressed format within a form. This is an alternative to using files or resources for translation storage and is most useful on mobile apps. The stored translations are automatically uncompressed, registered, and loaded into the Language Manager when the form is created. The translations will persist safely in the Language Manager even if the form is destroyed.
The package also introduces the TDKLanguageManager static class which is accessible directly or via the alias class LangManager (for backward compatibility. The manager is on first use. The Language manager performs all the tasks of maintaining the list of available translations or switching between them.
Not all text in an application is stored as component properties, such as messages, titles, labels, etc. For these occasions we have implemented a simple yet functional solution we call Constants.
You define a set of constants in the default language of your project using Project | Edit project constants... IDE menu item (a project must be open in IDE). This opens DKLang Constant Editor dialog allowing you to review, edit, add, or remove constants.
In order to link constant resource file to your project add the following line to the project source file (.dpr):
{$R *.dkl_const.res}
- A constant entry consists of a name - value pair.
- The name must meet the standard Delphi identifier naming requirements, i. e. consist of alphanumric, digit and underscore characters only and not start with a digit; the name must be unique (case makes no sense) over the whole list.
- The value is a Unicode value which can also be empty.
To read value of a constant you use its name (again, case-insensitively) and obtain a Unicode value using the function:
DKLangConstW('MyConstant')
You may use the freeware DKLang Translation Editor application to open the language source files (.dklang), and to create new translations (.lng files) based on them.
Warning: Do not edit .dklang files directly since the contents of these files are controlled automatically by language controllers and constant editor. Any changes to property mappings or constant values will be lost once the file is updated! Nevertheless, you can add your custom comments (each line starting with a semicolon) at the top of the file. The package leaves such comments intact.