| Prev | Chapter 4. OpenACS Developer's Guide | Next |
|---|
This document describes how to develop internationalized OpenACS packages.
At this point, we've only covered things that involve the message catalog: Dynamically picking a chunk of text to spit out based on the locale.
Each section below consists on one part about how to write new internationalized packages, and which explains the details of how it works, and then another part that talks about the process for internationalizing existing packages.
The following section will tell you how to deal with localizable text in ADP files, in TCL files, and in APM Parameters.
Internationalizing templates is about replacing human readable text in a certain language with intenral message keys, which can then be dynamically replaced with real human language in the desired locale.
There are 3 syntaxes to choose from: The short, the verbose, and the temporary. Each offer different advantages, but generally, what you want to do is use the short notation for new packages and use the temporary notation for internationalizing old packages, then have the APM translate those into the short notation.
The short: #message_key#
The advantage of the short syntax is that it's short. It's as simple as inserting the value of a variable.
The verbose: <trn key="message_key" locale="locale">default text</trn>
The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended anymore, but it can be convenient for development, because it still works even if you haven't created the message in the message catalog yet, because what it'll do is create the message key with the default text from the tag as the localized message.
The temporary: <#message_key original text#>
This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that stays in the page. As you'll see later, it'll be replaced with the short syntax by a special feature of the APM. You may leave out the message_key by writing an underscore (_) character instead, in which case a message key will be auto-generated by the APM.
We recommend the short notation for new package development.
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. #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.
Table 4.1.
| Parameter Name | Parameter Value |
|---|---|
| class_instance_pages_csv | #dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column |
| departments_pretty_name | #departments_pretty_name# |
Then, depending on how we retrieve the value, here's what we get:
Table 4.2.
| Command used to retrieve Value | Retrieved Value |
|---|---|
| parameter::get -localize -parameter class_instances_pages_csv | Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column |
| parameter::get -localize -parameter departments_pretty_name | Abteilung |
| parameter::get -parameter departments_pretty_name | #departments_pretty_name# |
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.
You're responsible for creating the keys in the message catalog yourself.
Let's deal with dates and times first. The way it works is as follows:
Get the date in ANSI format from the database (YYYY-MM-DD HH24:MI:SS, the time portion is optional). Name the column in the SQL statement something that ends in "_ansi", such as "posting_date_ansi". Example: to_char(posting_date, 'YYYY-MM-DD HH24:MI:SS') as posting_date_ansi
Use the Tcl command "lc_time_fmt" to format the date in pretty format. There are a number of standard, localizable formats to choose from (see below). Example: set posting_date_pretty [lc_time_fmt $posting_date_ansi "%q"]
Use the "*_pretty"-version in your ADP page.
Here's the list of standard date and time formats to choose from:
%c: Long date and time (Mon November 18, 2002 12:00 AM)
%x: Short date (11/18/02)
%X: Time (12:00 AM)
%q: Long date without weekday (November 18, 2002)
%Q: Long date with weekday (Monday November 18, 2002)
If the abbreviations seem a bit strange, it's because they are. Most of them are standardized (see man strftime for example). %q and %Q are our proprietary additions, and 'q' was just about the only letter left in the alphabet.
The command 'lc_fmt_time' allows you to pass in a specific date and time format as well, but please don't, because the whole point is to make it possible for administrators to change date and time formats site-wide based on locales.
Numbers are very easy to format. Just say lc_numeric $value, and it'll format the number using the appropriate decimal point and thousand separator for the locale.
We've created a couple of tools especially for internationalizing the pages of existing packages. The tools can be accessed from the "Manage Internationalization" linked from the package manager page for a package.
The process consists of four steps:
Replace text with tags: This is an automated process, which will try to automatically locate chunks of translatable text, auto-generate a reasonable message key, and surround the text with the temporary <#...#> notation mentioned above.
Manually verify each ADP file. If necessary, you can add additional <#...#> tags, or you can move or remove the ones set by the automated step.
Manually mark up Tcl files, marking up translatable text with the <#...#> notation.
Replace tags with keys: This is an automated process, which will replace the temporary <#...#> notation in both ADP and Tcl files with the appropriate notation for the type of file, and store the text in the message catalog. You need to run the process twice, once for ADP files, and once for Tcl files.
When you run this step, any modified files are backed up in a file with a ".orig" suffix. Those files are never overwritten, though, so the .orig file will always be the original page file, not the second-to-last file. Running this action multiple times is harmless.
The system will auto-generate suggested message keys.
... (WRITE MORE HERE!)
Next step is to internationalize parameters that contain localizable text. See the section Multilingual APM Parameters.