Appendix C: XLIFF architecture

4D supports the XLIFF standard for the localization of interface text and titles. This technology is used internally for 4D applications, and 4D developers as well as plug-ins developers will be able to benefit from this new implementation in their own customized applications and plug-ins. 

The principle for setting up a 4D application interface that is translated dynamically is as follows: all the elements that depend on the language (text, labels and pictures) are stored outside the application, as files, in a folder named Resources. In forms, menus, and so on, the labels and pictures are specified as references. When the application is executed, these elements are displayed dynamically from external files depending on the linguistic context. The XLIFF standard uniformizes the mode of referencing and displaying labels.

In the Form editor, you can see the "real" contents of static areas by clicking in the Form editor area or by choosing Show Format or Show Name in the Object menu:

Compatibility  note: In addition to XLIFF, 4D still supports the previous system, based on the concept of “resources” (of the STR# type). This system is nevertheless now obsolete. Both systems can be used at the same time, in particular in converted applications (this point is detailed in the following pages).

XLIFF (XML Localization Interchange File Format) is a dedicated standard for the localization process. It is used to describe the correspondence between a source language and a target language within an XML file. 

Actually, the XLIFF standard is a new alternative to resources-based localization systems. Various tools, including several freeware, can also be found to manage such files. 

For more information about the XLIFF standard, please refer to the official XLIFF 1.1 Specification that can be found at the following address:
http://www.oasis-open.org/committees/xliff/documents/xliff-specification.htm

Warning: The XLIFF standard is case sensitive.

In 4D, XLIFF can be used at the following locations:

• “Object Name” field in the Property List of the Form editor
• “Window Title” field in the Form Properties dialog box that can be accessed from the Explorer
• Static text, including titles of buttons, checkboxes, etc.
• Menu editor (except ObjectName syntax, see below)
• Help Tips editor (except ObjectName syntax, see below).

Notes:

• In order for the XLIFF reference to be recognized, it must be located at the beginning of the text area.
• You cannot display XLIFF references in the Help Tips editor. To use help tips based on XLIFF, enter the XLIFF references directly in the Help messages field of the Property List.

In 4D, you can use XLIFF references via one of the following syntaxes:

• :15115,3 syntax
  When this syntax is used with XLIFF files, the first value (15115 in the example) designates the id attribute of the group element.
  The second value (3 in the example) designates the id attribute of the trans-unit element.
  Compatibility note: This syntax is exactly the same as that of the “former generation” STR# resources, of the type “:xxxx,yyy” where xxxx is the number of the STR# resource and yyy is the element number. For example, “:15115,3” means that 4D must use the 3rd element of the STR# resource number 15115. This way you can keep a resource-based system in a converted database while installing a new XLIFF system. In fact, 4D will first try to locate and use the values corresponding to 15115,3 in all loaded XLIFF files; then, if it does not find the string, it will search for it in all the open resource files. With this mechanism, you can implement an XLIFF-based system in an application without having to edit your existing dynamic string references: you just need to copy an XLIFF file at the correct location (see below) and it will be taken into account by 4D. Both systems can be used simultaneously. In all cases, loaded XLIFF files have priority over resource files if the same string is present in both locations.

• :xliff:OKButton syntax
  This alternative syntax can only be used with loaded XLIFF files. In this case, the referenced value (OKButton in the example) designates the resname attribute of the trans-unit element.

• ObjectName syntax (based on the “Name” field in the Property list)
  The purpose of this syntax is to facilitate the translation of forms — unlike the other syntaxes, it is only used with forms. The principle is to surround the trans-unit elements in the XLIFF file by two group elements whose resname attributes contain, respectively, the table name and the form name.
  
  • Example (table form)
    To translate the title of the button whose object name is “SaveButton” in the “Form1” form of the [Clients] table, the XLIFF file simply need to contain the lines:
    

    <group resname="[Clients]">
    <group resname="Form1">
    <trans-unit resname="SaveButton">
    ...
    </trans-unit>
    </group>
    </group>

  • Example (project form)
    In a project form, the table name must be replaced by [ProjectForm], which produces the following:
    

    <group resname="[ProjectForm]">
    <group resname="Form1">
    <trans-unit resname="SaveButton">
     ...
    </trans-unit>
    </group>
    </group>

If you use different syntaxes in your database, the order of priority applied when searching a valid translation in the XLIFF files will be as follows:
1. “:15115,3” syntax
2. “:xliff:OKButton” syntax
3. “MyTitle” syntax

The Get indexed string and STRING LIST TO ARRAY commands of the “Resources” theme can use XLIFF documents.

You can see the XLIFF reference or the title translated according to the current language in the form editor using, respectively, the Show Name and Show Resource commands of the Object menu. For more information, refer to Using references in static text.

To implement an XLIFF architecture for your localized application, you just need to build one or more valid XLIFF file(s) and copy them into the Resources folder of the database.

For more information about the Resources folder of the database, refer to Managing the Resources folder. 

Here is the full pathname to use:

• Windows:
  MyDatabase\Resources\Lang.lproj\MyEnLoc.xlf

• Mac OS:
  MyPackage:Resources:Lang.lproj:MyEnLoc.xlf

where:

• MyDatabase is the folder that contains the database files and MyPackage is the database package under Mac OS.
• Lang.lproj is a folder that contains the XLIFF files for the Lang language. The name of the folder must comply with the international standard (see the following paragraph). For example, for English versions the folder should be named en.lproj.

4D will automatically load the XLIFF files in the folder corresponding to the current language of the database. To set the current language of the database, 4D carries out successive searches in the Resources folder of the database to find a language corresponding to (in the following order of priority):

1. The system language (under Mac OS, several languages can be set by order of preference, 4D uses this setting).
2. The language of the 4D application.
3. English
4. If none of these searches find anything, the first language found in the Resources folder is loaded.

The Get database localization command finds out what current language is specified for the database. 

If a language variation is used and is not available in the XLIFF files, the next closest language will be used.

XLIFF files can be named freely; they just need to have the extension “.xlf.”. You can place several XLIFF files in the same language folder; they will be loaded in the alphabetical order of the file names.

The name of the “.lproj” folder must respect one of the standards described below. 4D will look for a valid folder name based on each of these standards, in the following specific order:

1. Language-Regional Codes
   In this combination, a language is described by a Language code (ISO639-1) + a hyphen + either a Country code (ISO3166) or a 4-letters script code (ISO15924).
   For example, “fr-ca” (thus fr-ca.lproj) for the French-Canadian language.
2. ISO639-1
   This standard defines each language by two letters. For example, “en” (thus en.lproj) for the English language.
   Ref: http://www.loc.gov/standards/iso639-2/php/English_list.php
3. Legacy name
   In this convention, the language name is written out completely in English. For example, “english” (thus english.lproj) for the English language.
   Note: The first two conventions are supported only for Mac OS version 10.4 or higher. With previous versions of this OS, only the “Legacy” name can be used.

A summary table of the language codes supported by 4D is provided in Language codes. 

If several language definitions are found, 4D will always look for the most precise translations. For example, if the current OS language setting is “French Canadian,” 4D will first look for “fr-ca” translations and then, if not found, “fr” translations.

Note: The same principle applies within XLIFF files for the “target-language” tag. You must be sure to carefully set this attribute within the XLIFF files since a file located in the “fr-ca.lproj” folder that has a “target-language=fr” tag will be considered as a translation into “fr” and not “fr-ca.”

The XLIFF files are reloaded “dynamically” while you localize your application, so that you can see if the localized words or sentences fit into the object frames (buttons, group boxes, etc.). This reload occurs as 4D comes back to the front whenever the modification date or time has been changed since the last load.The current form will be reloaded simultaneously.

The following table lists the language codes supported by 4D for managing XLIFF files.