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.
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:
+ 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.
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:
set title "Messages for $a(name) in $b(label)"
set context [list [list . "SimPlay"] \
[list [export_vars -base case-admin { case_id }] \
@@ -26,17 +26,17 @@
<#_ Administer %a.name%#>] \
<#_ Messages for %a.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
-
Replace the temporary message tags in TCL files. Repeat step 2 for tcl files. Here is the example TCL file after conversion:
+
Replace the temporary message tags in Tcl files. Repeat step 2 for tcl files. Here is the example Tcl file after conversion:
set title [_ simulation.admin_title]
set context [list [list . [_ simulation.SimPlay]] \
[list [export_vars -base case-admin { case_id }] \
[_ simulation.lt_Administer_name_gt]] \
[_ simulation.lt_Messages_for_role_pre]]
-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. +
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 Multilingual APM Parameters
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:
+
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.
@@ -159,4 +159,4 @@
the message appears.
Avoid plurals. Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.
Quoting in the message catalog for tcl. Watch out for quoting and escaping when editing text that is also code. For example, the original string
set title "Patch \"$patch_summary\" is nice."
breaks if the message text retains all of the escaping that was in the tcl command:
<msg>Patch \"$patch_summary\" is nice.</msg>
When it becomes a key, it should be:
<msg>Patch "$patch_summary" is nice.</msg>
Also, some keys had %var;noquote%, which is not needed since those variables are not quoted (and in fact the variable won't even be - recognized so you get the literal %var;noquote% in the output).
Be careful with curly brackets. Code within curly brackets isn't evaluated. TCL uses curly brackets as an alternative way to build lists. But TCL also uses curly brackets as an alternative to quotation marks for quoting text. So this original code
array set names { key "Pretty" ...} ... if converted to
array set names { key "[_bug-tracker.Pretty]" ...} ... won't work since the _ func will not be called. Instead, it should be
array set names [list key [_bug-tracker.Pretty] ...]