Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 12 Mar 2004 13:44:56 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 22 Mar 2004 10:50:45 -0000 1.14
@@ -76,49 +76,8 @@
-
- Translator's Guide
- Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.
- The basic steps for translators:
-
-
- Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
-
-
-
- Translating with Translator Mode
- To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
-
-
-
-
-
-
- While in Translator mode, a list of all message keys appears at the bottom of each page.
-
-
-
-
-
-
-
-
- Batch translation
- To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.
-
-
-
-
-
-
-
-
-
-
-
- Introduction to Developing Internationalized Packages
-
+ How Internationalization/Localization works in OpenACS
This document describes how to develop internationalized OpenACS
packages, including writing new packages with
@@ -135,41 +94,24 @@
The main difference between monolingual and internationalized
- packages is that all user-visible text in an 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. Both script files
- (ADP/TCL) and APM parameters are affected.
+ 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.
-
-
-
-
- AOLserver Configuration for Multilingual Sites
-
-
- For multilingual websites we recommend using the UTF8
- charset. In order for AOLserver to use utf8 you need to set
- the config parameters OutputCharset and
- URLCharset to utf-8 in your AOLserver config file (use the etc/config.tcl
- template file). This is the default for OpenACS 5.1 and later. For sites running on Oracle you need to make
- sure that AOLserver is running with the NLS_LANG environment
- variable set to .UTF8. You should set this variable in the
- nsd-oracle run script (use the
- acs-core-docs/www/files/nds-oracle.txt template file).
-
-
-
-
- Using the Message Catalog
-
+
+ User Content
+ OpenACS does not have a general system for supporting multiple, localized versions of user-input content. This document currently refers only to internationalizing the text in the package user interface.
+
+
Localizable text must be handled in ADP files, in TCL files, and
in APM Parameters. OpenACS provides two approaches, message
@@ -182,13 +124,13 @@
distinguished by a file naming convention.
+
-
Separate Templates for each Locale
- 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.
-
-
-
+ 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 processed normally.
+
+
+ Message Catalogs
Message Keys in Template Files (ADP Files)
@@ -280,27 +222,24 @@
- 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.
+ 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 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 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 $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 the code. Here is an example of a dynamic lookup:
-set message_key_array {
- dynamic_key_1 \#package_key.message_key1\#
- dynamic_key_2 \#package_key.message_key2\#
+
+ 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 the code. Here is an example of a dynamic lookup:
+
+ set message_key_array {
+ dynamic_key_1 \#package_key.message_key1\#
+ dynamic_key_2 \#package_key.message_key2\#
}
-set my_text [lang::util::localize $message_key_array([get_dynamic_key])]
-
-
-
+ set my_text [lang::util::localize $message_key_array([get_dynamic_key])]
+
@@ -408,34 +347,22 @@
procedure.
-
+
-
+ Dates, Times, and Numbers in TCL files
- Checking the Consistency of Catalog Files
-
-
- 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:
-
-
-
- acs-lang/bin/check-catalog.sh package_key
-
-
-
- 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.
-
-
+
+ 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 readable at
+ lang::system::timezone.. When
+ retrieved from the database and displayed, dates and times must
+ be localized to the user's locale.
+
+
@@ -535,42 +462,225 @@
+
-
+
+ How to Internationalize a Package
- Dates, Times, and Numbers
-
-
- 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 readable at
- lang::system::timezone.. When
- retrieved from the database and displayed, dates and times must
- be localized to the user's locale.
+
+
+ For multilingual websites we recommend using the UTF8
+ charset. In order for AOLserver to use utf8 you need to set
+ the config parameters OutputCharset and
+ URLCharset to utf-8 in your AOLserver config file (use the etc/config.tcl
+ template file). This is the default for OpenACS 5.1 and later. For sites running on Oracle you need to make
+ sure that AOLserver is running with the NLS_LANG environment
+ variable set to .UTF8. You should set this variable in the
+ nsd-oracle run script (use the
+ acs-core-docs/www/files/nds-oracle.txt template file).
+
+
+
+ Replace all text with temporary message tags
+ From/acs-admin/apm/, select a
+ package and then click on
+ Internationalization, then
+ Convert ADP, Tcl, and SQL files to using the
+ message catalog.. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.
+
+
+
+
+
+
+ You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key.
+
+
+
+
+
+
+ The automatic process can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:
+ <p class="form-help-text"><b>Invitations</b> are sent,
+ when this wizard is completed and casting begins.</p>
+ has a bold tag which confuses the converter into thinking there are two message keys for the text beginning "Invitations ..." where there should be one:
+
+
+
+
+
+ Instead, we cancel those keys, edit the file manually, and put in a single temporory message tag:
+ <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent,
+ when this wizard is completed and casting begins.#>
+ </p>
+
+
+ Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:
+
+Select which case <if @simulation.casting_type@ eq "open">and
+role</if> to join, or create a new case for yourself. If you do not
+select a case <if @simulation.casting_type@ eq "open">and role</if>
+to join, you will be automatically assigned to a case <if
+@simulation.casting_type@ eq "open">and role</if> when the
+simulation begins.
+ ... can be rewritten:
+<if @simulation.casting_type@ eq "open">
+
+Select which case and role to join, or create a new case for
+yourself. If you do not select a case and role to join, you will
+be automatically assigned to a case and role when the simulation
+begins.
+
+</if>
+<else>
+
+Select which case to join, or create a new case for
+yourself. If you do not select a case to join, you will
+be automatically assigned to a case when the simulation
+begins.
+
+</else>
+
+
-
- Get the date in ANSI format from the database (YYYY-MM-DD
- HH24:MI:SS; the time portion is optional). By convention,
- we identify dates in ansi format by ending the column name
- with _ansi.
- Example:
- select to_char(posting_date, 'YYYY-MM-DD HH24:MI:SS') as posting_date_ansi
- from table
-
+
+ Replace the temporary message tags in ADP files
+ From the same Convert ADP ... page in /acs-admin/apm as in the last step, repeat the process but deselect Find human language text ... and select Replace <# ... #> tags ... and click OK. This step replaces all of the temporary tags with "short" message lookups, inserts the message keys into the database message catalog, and then writes that catalog out to an xml file.
+
+
+
+ Replace human-readable text in TCL files with temporary tags
+ Examine all of the tcl files in the packages for human-readable text and replace it with temporary tags. The temporary tags in TCL are slightly different from those in ADP. If the first character in the temporary tag is an underscore (_), then the message keys will be auto-generated from the original message text. Here is an unmodified tcl file:
+
+ ad_page_contract {
+ List of messages for a case
+} {
+ case_id:integer
+ role_id:integer
+}
+set workflow_id [simulation::case::get_element -case_id $case_id -element workflow_id]
+set simulation_name [simulation::template::get_element -workflow_id $workflow_id -element pretty_name]
+workflow::role::get -role_id $role_id -array role_array
+simulation::case::get -case_id $case_id -array case_array
+
+set title "Messages for $role_array(pretty_name) in $case_array(label)"
+set context [list [list . "SimPlay"] [list [export_vars -base case-admin { case_id }]
+ "Administer $case_array(label)"] "Messages for $role_array(pretty_name)"]
+
+set user_id [ad_conn user_id]
+... and here is the same file after temporary message tags have been manually added:
+
+ad_page_contract {
+ List of messages for a case
+} {
+ case_id:integer
+ role_id:integer
+}
+
+set workflow_id [simulation::case::get_element -case_id $case_id -element
+workflow_id]
+set simulation_name [simulation::template::get_element -workflow_id
+$workflow_id -element pretty_name]
+workflow::role::get -role_id $role_id -array role_array
+simulation::case::get -case_id $case_id -array case_array
+
+# Variables used by I18N messages (array variables not currently
+supported)
+set role_pretty_name $role_array(pretty_name)
+set case_pretty_name $case_array(label)
+set title <#case_admin_page_title Messages for %role_pretty_name% in
+%case_pretty_name%#>
+set context [list [list . <#_ SimPlay#>] [list [export_vars -base
+case-admin { case_id }] <#_ Administer %case_pretty_name%#>] <#_ Messages
+for %role_pretty_name%#>]
+ Note that the message key case_admin_page_title was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing
+
+
-
- Use the Tcl command lc_time_fmt to format the
- date in "pretty" format. Several standard formats localize automatically:
+
+ Replace the temporary message tags in TCL files
+ Repeat step 2 for tcl files. Here is the example TCL file after conversion:
+
+ ad_page_contract {
+ List of messages for a case
+} {
+ case_id:integer
+ role_id:integer
+}
+
+set workflow_id [simulation::case::get_element -case_id $case_id -element
+workflow_id]
+set simulation_name [simulation::template::get_element -workflow_id
+$workflow_id -element pretty_name]
+workflow::role::get -role_id $role_id -array role_array
+simulation::case::get -case_id $case_id -array case_array
+
+# Variables used by I18N messages (array variables not currently
+supported)
+set role_pretty_name $role_array(pretty_name)
+set case_pretty_name $case_array(label)
+set title [_ simulation.case_admin_page_title]
+set context [list [list . [_ simulation.SimPlay]] [list [export_vars
+-base case-admin { case_id }] [_ simulation.lt_Administer_case_prett]] [_
+simulation.lt_Messages_for_role_pre]]
+
+set user_id [ad_conn user_id]
+
+
+
+ Internationalize SQL Code
+ If there is any user-visible TCL code in the .sql or .xql files, internationalize that the same way as for the TCL files.
+
+
+
+
+ Internationalize Package Parameters
+
+ See
+
+
+
+
+
+ Internationalize Date and Time queries
+
+
+
+
+ Find datetime in .xql files. Use command line tools to find suspect SQL code:
+ grep -r "to_char.*H" *
+grep -r "to_date.*H" *
+
+
+
+ In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
+ to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
+ becomes
+ to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
+
+
+
+ In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
+
+set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
+ When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system.
+
+
+ When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
+ set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
+
+
+ Use the _pretty version in your ADP page.
+
+
+
@@ -610,82 +720,52 @@
strftime).
- set posting_date_pretty [lc_time_fmt $posting_date_ansi "%q"]
-
+
+
-
-
- Use the *_pretty version in your ADP page.
-
+
+ Internationalize Numbers
+
+ To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale.
+
+
-
-
+
+
+ Internationalizing Forms
+ When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
+
+
-
- To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale.
-
-
-
+
+
-
- Internationalizing Forms
- When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
-
-
+ Checking the Consistency of Catalog Files
-
-
- Internationalizing Existing Packages
-
-
- Internationalize Message text in ADP and TCL
-
- 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..
-
-
-
- Internationalize Package Parameters with visible messages
- See
-
-
+ 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:
+
+
+
+ acs-lang/bin/check-catalog.sh package_key
+
-
- Internationalize Date and Time queries
-
-
- Find datetime in .xql files. Use command line tools to find suspect SQL code:
- grep -r "to_char.*H" *
-grep -r "to_date.*H" *
-
-
-
- In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
- to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
- becomes
- to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
-
-
-
- In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
-
-set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
- When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system.
-
-
-
- When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
- set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
-
-
-
+
+ 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.
+
+
+
@@ -704,4 +784,43 @@
found, then that locale is offered instead.
+
+ Translator's Guide
+ Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.
+ The basic steps for translators:
+
+
+ Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
+
+
+
+ Translating with Translator Mode
+ To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
+
+
+
+
+
+
+ While in Translator mode, a list of all message keys appears at the bottom of each page.
+
+
+
+
+
+
+
+
+ Batch translation
+ To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.
+
+
+
+
+
+
+
+
+
+