If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are still processed.

Internationalizing templates is about replacing human readable text in a certain language with internal message keys, which can then be dynamically replaced with real human language in the desired locale. Message keys themselves should be in ASCII English, as should all code. Three different syntaxes are possible for message keys.

"Short" syntax is the recommended syntax and should be used for new development. When internationalizing an existing package, you can use the "temporary" syntax, which the APM can use to auto-generate missing keys and automatically translate to the short syntax. The "verbose" syntax is useful while developing, because it allows default text so that the page is usable before you have done localization.

We recommend the short notation for new package development.

In adp files message lookups are typically done with the syntax \#package_key.message_key\#. In Tcl files all message lookups *must* be on either of the following formats:

Translatable texts in page TCL scripts are often found in page titles, context bars, and form labels and options. Many times the texts are enclosed in double quotes. The following is an example of grep commands that can be used on Linux to highlight translatable text in TCL files:

# Find text in double quotes
find -iname '*.tcl'|xargs egrep -i '"[a-z]'

# Find untranslated text in form labels, options and values
find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'

# Find text in page titles and context bars
find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'

# Find text in error messages
find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'

      

You may mark up translatable text in TCL library files and TCL pages with temporary tags on the <#key text#> syntax. If you have a sentence or paragraph of text with variables and or procedure calls in it you should in most cases try to turn the whole text into one message in the catalog (remember that translators is made easier the longer the phrases to translate are). In those cases, follow these steps:

The variable values in the message are usually fetched with upvar, here is an example from dotlrn:

was replaced by:

This kind of interpolation also works in adp files where adp variable values will be inserted into the message.

Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes:

set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]

ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted $msg_subst_list]

When we were done going through the tcl files we ran the following commands to check for mistakes:

# Message tags should usually not be in curly braces since then the message lookup may not be
# executed then (you can usually replace curly braces with the list command). Find message tags 
# in curly braces (should return nothing, or possibly a few lines for inspection)
find -iname '*.tcl'|xargs egrep -i '\{.*<#'

# Check if you've forgotten space between default key and text in message tags (should return nothing)
find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'

# Review the list of tcl files with no message lookups
for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done

When you feel ready you may vist your package in the package manager and run the action "Replace tags with keys and insert into catalog" on the TCL files that you've edited to replace the temporary tags with calls to the message lookup procedure.

This section describes how to check that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in the catalog file are identical. The scripts below assume that message lookups in adp and info files are on the format \#package_key.message_key\#, and that message lookups in tcl files are always is done with one of the valid lookups described above. The script further assumes that you have perl installed and in your path. Run the script like this:

where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks primarily on en_US xml catalog files.

Some parameters contain text that need to be localized. In this case, instead of storing the real text in the parameter, you should use message keys using the short notation above, i.e. #package_key.message_key#.

In order to avoid clashes with other uses of the hash character, you need to tell the APM that the parameter value needs to be localized when retrieving it. You do that by saying: parameter::get -localize.

Here are a couple of examples. Say we have the following two parameters, taken directly from the dotlrn package.

Then, depending on how we retrieve the value, here's what we get:

The value in the rightmost column in the table above is the value returned by an invocation of parameter::get. Note that for localization to happen you must use the -localize flag.

The locale used for the message lookup will be the locale of the current request, i.e. lang::conn::locale or ad_conn locale.

Developers are responsible for creating the keys in the message catalog, which is available at /acs-lang/admin/

Acs-lang includes tools to automate some internationalization. From /acs-admin/apm/, select a package and then click on Internationalization, then Convert ADP, Tcl, and SQL files to using the message catalog..

See the section called “Checking the Consistency of Catalog Files”