Application Localization

Scope

Objects: All
Languages: Java, .NET, .NET Mobile, Visual Basic, RPG, Cobol
Interfaces: Web, Win

Introduction

Automatic translation is a process carried out at specification time that changes every string constant (see exceptions below) by its translated counterpart (static translation).

What is translated ?

The Automatic translation process translate every string constant that appears in your GeneXus code.
Exceptions are:

• String literals in HTML forms (those that are not TextBlocks)
• String literals that you do not want to be translated (see below)
• Help (see more in Help Translation )

A "string constant" is a set of characters enclosed in single or double quotes used in your application code. Value ranges, Enumerated domain, Combo box and Radio button values are also string constants. They are case sensitive and leading/trailing spaces are ignored.

To avoid translating a string constant you must prefix it with the ! character as in:

• !"Client name" or !'Client name'

The translation cycle

Using 9.0 version a new folder called Localization is created:



When a knowledge base is created or converted, GeneXus creates automatically in the Localization folder a "language object" (a new type of Genexus object) for each predefined language (English, Italian, Portuguese, Simplified Chinese Spanish, Traditional Chinese).

When automatic translation is activated, GeneXus builds a list of string constants used in your GeneXus code as objects are specified. These string constants are assumed to be in the Language specified in the Language Master Model property (File/Edit Model in Design). Once the above list is complete and all its string constants are translated by the corresponding person to the target language, your application will be also translated.

The steps required to translate your application are:

1 - Setup the Translate property to "Static" in the prototype/production model.
2 - Select the target language in the Translate to language property.
3 - Specify the entire application. In this way, all captions to be translated are created in the Language objects, ready to be translated.
4 - Translate all captions in the selected Language object.
5 - Specify and generate the application (so the translation is actually achieved)

Static translation

Static translation is available for all generators. It provides the best performing code as no run-time overhead is added: translation is performed at specification time. Having your application in different languages requires different executables (one for each language).

So, if you plan to have your application translated to different languages you should set up a new Model for every new language you want to translate to.

Note: We talk about "static translation" in oppositon to "dynamic translation". The last one is not implemented yet, but its inclusion is due in future versions, to Java, .Net and .Net Mobile generators. Because of that the Translate property takes the "No translation" and "Static" values (as we'll mention below) rather than "Yes" and "No".

The Language Object

To be able to translate your application you must first select one of the predefined Language objects or create a new one. A Language object defines a new language that can be referenced later for translation. Language objects have several properties and the list of string constants already found in your code (none if you did not specify any program) ready to be translated.

Language Object Properties

Translation Model Properties

Translation Knowledge Base Properties

Examples are: HTML code, SQL Statements, strings representing numbers, underlining, etc. Regular expression syntax is described in http://www.boost.org/libs/regex/doc/syntax.html. A partial list of the default regular expressions distributed follows:

Predefined GeneXus Languages

When you create a new Knowledge Base or open an existing one a set of predefined string constants and Languages are created (or updated if they already existed) in it. They are used in the generated code for messages, button captions, etc.

The predefined languages are:

• English
• Italian
• Portuguese
• Simplified Chinese
• Spanish
• Traditional Chinese

Language Consolidation and Distribution

New options are included for the language management.

Distribution Options

• Include GeneXus messages --> Include the GeneXus messages in the XPZ
• Include untranslated messages --> Include the untranslated messages in the XPZ

Consolidation Options

• Update translations --> Updates the translations of the language with the existing in the XPZ, adding the new translations that can have in the XPZ. Translations not included in the XPZ are not deleted.
• Keep translations --> Only add the translation of the XPZ that doesn't exist in the language object.
• Replace all translations --> The language object of the XPZ completely replaces the existing one in the Knowlegde base.

Programming considerations

Language names and description criteria

Sharing translations among Genexus users word-wide can save translation time. It can be achived if we all have a well known Language naming convention. ARTech suggests using the English name of languages as Language object names and the language name in the actual language as Language object description. For example: Spanish: Español, Italian: Italiano, etc.

Format function

The Format() function is very important for translation purposes as statements may be build different in different languages. The syntax of this function is: Format( <FormatExpression>, <StringExpression1>[, ...] ).

FormatExpression is a string expression (character or varchar) having zero or more parameter markers (up to 9, from 1 to 9). For example: Format( "%1's age is %2 years old.", "John", "13"). In the example, parameter markers are %1 and %2. They state where, in the resulting string, must be embeded the values of "John" and "13". The result must be "John's age is 13 years old".

If a '%' sign must be included in FormatExpression it must be preceded by the '\' (backslash) sign. For example: "This is not a parameter marker: \%1".

Avoiding automatic string constant translation

There are constants in an application that should not be translated. To avoid translating a string constant you must specify the ! sign as the starting string constant character as in the following examples.

• "Client name" or 'Client name' will be translated
• !"Client name" or !'Client name' will not be translated

Common translation problems

Tranlated Conditions/Where/Ifs
In some cases the translated application does not properly work with existing data. This is the case of, for example, this comparison: ClientCategory = "Good". When translated to Spanish, the generated code should look like: ClientCategory = "Bueno", that is fine as long as you do want to run it agains your current Spanish data. The underlying problem is that Data Base data has translatable text ("Good" in the example).

Alternatives to fix the problem are:

• Use Enumerated domains. Enumerated Domain codes are not translated but their descriptions are.
• Change the literal to a non translatable literal !"Good"