I18n with kbmMW #2 – The simple way

Preface

In the just released 5.16.xx kbmMW Enterprise Edition we added a new feature, internationalization also called I18n.

The idea about i18n, is to be able to translate an application in such a way that it is fully usable in other languages, and preferably it also contains the ability to allow end users easily to switch to their preferred language.

Please read more in the first blog post about i18n, here.

How to internationalize an application

Let us make a sample VCL application (the same procedure can be followed for a Firemonkey application).

In the units Uses clause we add:

uses
  <snip>,
  kbmMWI18N, kbmMWI18NVCL;

In the forms OnCreate event handler we add:

procedure TForm1.FormCreate(Sender: TObject);
begin
     // Register the form as something to auto translate.
     i18n.RegisterComponent(self);
     i18n.IgnoreComponent(cbLanguage);

     // Load the translation description file test.yaml if it exists.
     i18n.Load('','test.yaml');

     // List languages known to the i18n framework (currently only from test.yaml) in a combo.
     cbLanguage.Items.AddStrings(i18n.LanguageNames);
     cbLanguage.ItemIndex:=0;
end;

In the forms OnClose event we add:

procedure TForm1.FormClose(Sender: TObject; var Action: TCloseAction);
begin
     // Merge discoveries made in this application into the test.yaml file
     // that may already exist.
     // If you do not care about merging changes, you can simply use Save.
     i18n.Merge('','test.yaml');
end;

and in the cbLanguage’s OnChange event we add:

procedure TForm1.cbLanguageChange(Sender: TObject);
begin
     i18n.CurrentLanguage:=cbLanguage.Text;
end;

Now we have everything that is needed for translating this application.

The first thing that happens when the application starts (this form is created), is that we register the form itself to be translated. That includes all components and sub components on the form.

The combo box (cbLanguage) on the form, containing language names which we use for selecting current language, we do not wish to be translated, so we exclude that particular one from translation.

Next we use the new simple syntax for loading or automatically create a translation document, which in this case is called test.yaml. The simple syntax will always use YAML format. If you prefer JSON, please use the more elaborate syntax described in the first blogpost.

Next we add the known list of languages to the cbLanguage combo box, and select the first one.

As the application runs, all texts for all components on the form (except the excluded cbLanguage) will be attempted to be translated. Since we have only provided two arguments for Load and thus left the optional 3rd one as default true, we are learning while attempting to translate. That means that new, never before seen texts/phrases, will be added to the internal translation knowledge.

Later when we close the application again, we ask the i18n framework to merge the new knowledge gained while running the application with whatever is already in test.yaml, thus attempting to preserve whatever comments or other things you may manually have entered into the file.

Since there were no test.yaml from start, one will be generated, with a language called Default. You can rename that to for example UK, or whatever is the language that is used in your application.

Then you can copy the whole section from and including UK and paste it in at the bottom and name it DE if you need a German translation.

languages: 
  UK: 
---
    propertyNames : [ Caption, Text, Items, Strings ]
    properties    : ~

  DE: 
---
    propertyNames : [ Caption, Text, Items, Strings ]
    properties    : ~

Make whatever changes to the DE section as you need (typically in the phrases section), and save it. Then next time you run your application, you will be able to switch between UK and DE as languages, and all your components are automatically translated.

Internationalizing your exceptions

The release included an additional feature, the ability to translate (or internationalize) your exception messages, automatically.

To enable that, you need to open your kbmMWConfig.inc file and add the following statement:

{$DEFINE KBMMW_INSTALL_EXCEPTION_I18N} 

Then recompile kbmMW runtime and designtime packages (remember you can use the CompileTool for that to make it easy).

Now all application exceptions (which do except some OS exceptions, like divide by zero), will be handled by the i18n framework, and attempted translated before being send on to the relevant exception handlers.

If you have enabled learning and make sure to either save or merge your in memory version of the i18n state to a file, you will be able to provide translations for other languages for your exception texts, by simply modifying or adding to the phrases section.

Happy translating!