This document describes how to develop internationalized OpenACS packages, including writing new packages with internationalization and converting old packages. Text that users might see is -"localizable text"; replacing monolingual text and single-locale -date/time/money functions with generic functions is -"internationalization"; translating first generation text into a -specific language is "localization." At a minimum, all packages -should be internationalized. If you do not also localize your -package for different locales, volunteers may use a public -"localization server" to submit suggested text. Otherwise, your -package will not be usable for all locales.
The main difference between monolingual and internationalized +"localizable text"; replacing monolingual text and +single-locale date/time/money functions with generic functions is +"internationalization"; translating first generation text +into a specific language is "localization." At a minimum, +all packages should be internationalized. If you do not also +localize your package for different locales, volunteers may use a +public "localization server" to submit suggested text. +Otherwise, your package will not be usable for all locales.
The main difference between monolingual and internationalized packages is that all user-visible text in the code of an -internationalized package are coded as "message keys." The message -keys correspond to a message catalog, which contains versions of -the text for each available language. Script files (.adp and .tcl -and .vuh), database files (.sql), and APM parameters are -affected.
Other differences include: all dates read or written to the +internationalized package are coded as "message keys." +The message keys correspond to a message catalog, which contains +versions of the text for each available language. Script files +(.adp and .tcl and .vuh), database files (.sql), and APM parameters +are affected.
Other differences include: all dates read or written to the database must use internationalized functions. All displayed dates must use internationalized functions. All displayed numbers must use internationalized functions.
Localizable text must be handled in ADP files, in Tcl files, and @@ -49,7 +49,7 @@
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
+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,
@@ -67,18 +67,19 @@
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.
"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.
The short:
#package_key.message_key#
-
The advantage of the short syntax is that it's short. It's as -simple as inserting the value of a variable. Example: +
The advantage of the short syntax is that it's short. +It's as simple as inserting the value of a variable. Example: + <span>#</span>forum.title#
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. Example: <trn key="forum.title" +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. Example: +<trn key="forum.title" locale="en_US">Title</trn>
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 +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. Example: <_ Title> @@ -116,11 +118,11 @@ formats:
Typical static key lookup: [_
package_key.message_key] - The message key and package key
-used here must be string literals, they can't result from variable
-evaluation.
Static key lookup with non-default locale: [lang::message::lookup $locale
+used here must be string literals, they can't result from
+variable evaluation.
Static key lookup with non-default locale: [lang::message::lookup $locale
package_key.message_key] - The message key and package key
-used here must be string literals, they can't result from variable
-evaluation.
Dynamic key lookup: [lang::util::localize
+used here must be string literals, they can't result from
+variable evaluation.
Dynamic key lookup: [lang::util::localize
$var_with_embedded_message_keys] - In this case the message
keys in the variable var_with_embedded_message_keys must appear
as string literals \#package_key.message_key\# somewhere in
@@ -161,14 +163,14 @@
text_with_percentage_vars#>) and run the action replace tags
with keys in the APM.
The variable values in the message are usually fetched with
-upvar, here is an example from dotlrn: ad_return_complaint 1 "Error: A [parameter::get
--parameter classes_pretty_name] must have
+upvar, here is an example from dotlrn: ad_return_complaint 1 "Error: A
+[parameter::get -parameter classes_pretty_name] must have
<em>no</em>[parameter::get -parameter
-class_instances_pretty_plural] to be deleted" was replaced
-by: set subject [parameter::get
--localize -parameter classes_pretty_name] set class_instances
-[parameter::get -localize -parameter class_instances_pretty_plural]
-ad_return_complaint 1 [_
+class_instances_pretty_plural] to be deleted" was
+replaced by: set subject
+[parameter::get -localize -parameter classes_pretty_name] set
+class_instances [parameter::get -localize -parameter
+class_instances_pretty_plural] ad_return_complaint 1 [_
dotlrn.class_may_not_be_deleted]
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
@@ -183,25 +185,25 @@
# 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)
+# 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.
Most date, time, and number variables are calculated in Tcl
files. Dates and times must be converted when stored in the
database, when retrieved from the database, and when displayed. All
-dates are stored in the database in the server's timezone, which is
-an APM Parameter set at /acs-lang/admin/set-system-timezone and
+dates are stored in the database in the server's timezone,
+which is an APM Parameter set at /acs-lang/admin/set-system-timezone and
readable at lang::system::timezone.. When retrieved
from the database and displayed, dates and times must be localized
-to the user's locale.
Then, depending on how we retrieve the value, here's what we +
Then, depending on how we retrieve the value, here's what we get: