Internationalization and Localization

Internationalization consists on making it possible to perform the localization of an application, and localization is the process to adapt an application to a certain culture or locale, usually defined by a combination of language and country, known as locale. Localization involves not only translation; aspects like currency or date formats may also change from one country to another, even between countries that share a language.

Both web and mobile server applications developed with HTML5 Builder can by internationalized and localized to any language. You can translate texts, but also change images, relocate components, etc.

Internationalization

Components Internationalization

Components include built-in internationalization features, so you can localize them right away.

Server-side Code Internationalization

Wrapping with Gettext Functions

To internationalize a string in server-side code, first you must wrap it with the _() function (which is an alias for gettext()):

echo _("You will be able to translate this string.");

Certain strings might contain variable values. For those, you should use functions for formatted strings, such as printf() (to print a formatted string) or sprintf() (to generate a formated string).

printf("The string "%s" will be printed no matter which locale is being used.", $string);

The localized versions of the string above would translate the sentence, but leave the %s code untouched. Whenever the string is printed, the %s will get replaced by the content of the $string variable.

For strings with a plural form you should wrap the target string with ngettext() instead:

printf(ngettext("%d thing (singular).", "%d things (plural).", $amount), $amount);

PO Files Generation

PO is a file format for string-based translation. The file contains a list of strings in a source language, and for each string there is a second (initially empty) string that must be filled with a translation of the source string into the target language.

Once the translatable strings have been wrapped with Gettext functions, its is time to get a PO file generated for each language you are going to translate your application to.

Access the Internationalization wizard from Home > Internationalize, and go through all the steps. You will choose the files you can to search for translatable strings, as well as the languages you want to generate a PO file for.

A locale folder will be created at the root of your project, and each PO file will be located at locale\Language\LC_MESSAGES\messages.po.

Localization

Components Localization

To localize the components of a page as well as the page itself, web or mobile, follow these steps:

1. Set the Language property of the page to the target locale.
2. Perform the localization, that is, customize the properties of your components to adapt them to the target locale. For example, you can translate the captions of labels and buttons. Your changes will be recorded on a resource file named after the target locale: FileName.LocaleName.xml.php. For example: unit1.German.xml.php.
3. Repeat the previous steps for as many locales as you want.

The resource files for the different locales will only contain the differences from the content of the main page, so you can continue developing the main page, and the localizations will still work.

Resource files are basically XML files (human-readable), so they can be edited with any plain text editor by a translator. Also, if you want to remove any of the changes on the localization (for example, if you accidentally modified the position of a component), remove the relevant parts from the resource file and the values from the main form will be used again, and changes to those values on the main form will also affect the localized version.

Server-side Code Localization

Once the PO files are generated, it is time to translate them. You can do so with a plain text editor, or with your favourite translation edition tool. A good choice could be Poedit, that will take also care of the next step.

After you translate the PO files, you have to compile them into MO files. There are several tools you can use to achieve this. Poedit, for example, automatically generates a MO file when you save your changes to the PO file.

Locale Switch

To switch to a different locale than the one the page was loaded with, just change the Language property of the application and the page (in that order).

$locale = "Target Locale Name"; global $application; $application->Language = $locale; $this->Language = $locale;

For example, to switch to the French locale when a button is clicked, assign the following event handler to the OnClick event of the Button component:

function setFrenchLanguage($sender, $params) {
  $locale = "French";

  global $application;
  $application->Language = $locale;

  $this->Language = $locale;
}

Autodetect the Locale

Use the following code to set the language of your application and page to that of the web browser in which your page was opened:

global $application; $application->autoDetectLanguage(); $this->Language = $application->Language;