i18n

• Infrastructure for selecting the desired localization
• Localizing strings located in Pike code, such as controllers
• Localizing strings located in Fins templates
• Localizing text contained within an application's data model (in progress)

The get_lang() method located in Fins.Request is the key to Localization of strings. This method uses a client browser's language settings to select the desired language. Currently, this is a rather simplistic algorithm which does not take into consideration the available languages in an application.

get_lang() should be used with the standard Pike localization tools to provide strings that are translated automatically into the correct locale for the requesting browser.

Localizing Pike Code

Pike code can be localized using the Locale module, which provides a fairly flexible localization system. The http://www.gotpike.org/PikeWiki/index.pike/PikeDevel/I18n page at the Pike wiki describes the process of extracting and translating strings in Pike code. The tools available for localizing templates are built upon the Locale module, so it makes sense to become familiar with that before moving on to the following material.

The Fins application creation tool (pike -x fins create) automatically creates a localization configuration file as config/locale.xml, and uses the same format as the standard Pike localization file. This configuration file is used by the Locale string extractor tool which will be discussed later.

Fins.Application includes code to automatically set a Localization search for the current APPNAME. This path is set to APPDIR/translations/LANG/APPNAME.xml, where LANG is the 3 character ISO language code for a given translation, and APPNAME is the name of the project containing translated strings. You may wish to provide a default search path for other projects if, for example, your app provides a plugin infrastructure.

Localizing Template Strings

Just as Pike code can be divided into multiple localization projects, the Simple template system provides a mechanism for specifying the project to be used for locating string translations. By default, the default project name is the same as your application, and is stored in the Request object. The project name may be changed using the following syntax:

  <%@ project name="MyProject" %>

Note that included files may change this project value; it is important to reset the project after including files which may use a different project.

Once you have specified the desired project, individual strings may be marked as localized. Similar to the method for performing this task in Pike code, the Simple template system provides a macro for translating strings into the desired language:

  <% LOCALE id="0" string="Hello, World!" %>

Note that initially the id attribute is optional; if it is not present, the string will be considered new, and will be assigned an id when localized strings are extracted the next time. Once an id is assigned, do not remove or change it, otherwise the string extractor will duplicate the string to be translated within the string translation file.

Extracting Strings from Templates

Fins includes a version of the extract_locale tool provided with Pike. this version of the tool has been modified to support extraction of strings from Simple templates.

This tool operates the same way as the standard string extractor, and is available using the following command:

  pike -x fins extract_locale [args] [file1 [… filen]]

So, for example, we wanted to extract localized strings from a simple template, as well as a controller, we might use the following command line:

  pike -x fins extract_locale --config=config/locale.xml classes/controller.pike templates/index.phtml

An easier approach is to specify the names of all files to search for localized strings in the locale configuration file. The following command can be used to generate a list of phtml files for insertion in your locale.xml:

find templates -type f -name &#42;.phtml -print | sed -e 's/^/<file>/' -e 's_$_</file>_'

Selecting Languages

Fins provides a method in the Request object that returns the currently chosen 3 digit language code. This calculation is made once, and cached in the session storage until one of the factors that determines that value changes. By default, Fins will use the "accept-language" header sent by a browser to determine the language to use. If a requested language is not available, Fins will fall back to "eng" or the value of the application->default_language value set in your application's cnfiguration file.

Additionally, there are a set of macros that can be used to allow a user o manually select their desired language. These techniques rely on the fact that the Fins based Request objects treat the "_lang" variable specially when passed from a browser form. If present, the value of the "_lang" variable should be a 2 or 3 digit language code, and will be used to select the locale, overriding any pre-existing language set by the application. Note that the locale must still exist in the translations directory.

The language_selector macro generates a form with a dropdown displaying available languages, displayed natively. If your application uses a less popular language, you should verify that it is provided in the Tools.Language.Names module.

For users wishing a more customized selection process, you can use application->available_languages() or the available_languages macro to get a set of available languages as a mapping with 3 digit language codes to native names. You may then generate a form which sets the "_lang" form variable.

Future Directions

• Tools for localizing numbers and other non-string values. (Pike includes methods for performing some of these operations; this note specifically refers to exposing those tools to Simple template users.)
• Provision for using locale specific templates, if available (as the needs of a given locale may require changes beyond simply translating output.)

Not categorized | RSS Feed | BackLinks