How to Internationalize a Package

Prev	Chapter 14. Internationalization	Next

Tip

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 temporary 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>
```
- Check for duplicate keys. For common words such as Yes and No, you can use a library of keys at acs-kernel. For example, instead of using myfirstpackage.Yes, you can use acs-kernel.Yes. You can also use the Message Key Search facility to find duplicates. Be careful, however, building up sentences from keys because grammar and other elements may not be consistent across different locales.
  Additional discussion: Re: Bug 961 ("Control Panel" displayed instead of "Administer"), Translation server upgraded, and Localization questions.
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 }] \ 
                    "Administer $a(name)"] \
                  "Messages for $a(name)"]
```
... and here is the same file after temporary message tags have been manually added:
```
set title <#admin_title Messages for %a.name% in %b.label%#>
set context [list [list . <#_ SimPlay#>] \
                  [list [export_vars -base case-admin { case_id }] \
                    <#_ 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:

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. See Multilingual APM Parameters
Internationalize Date and Time queries.
1. Find datetime in .xql files. Use command line tools to find suspect SQL code:
```
grep -r "to_char.*H" *
grep -r "to_date.*H" *
```
2. 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
```
3. 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.
4. 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.
  - %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)
  The "q" format strings are OpenACS additions; the rest follow unix standards (see man strftime).
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.
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.

Common mistakes while internationalizing

Don't internationalize internal code words. Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.
These notes haven't been formatted yet:

There are a nubmer of instances of constructing sentences via concatination (you
can just look at keys like:
  <msg key="Page_with_pagination">Page with  [ %pagination_filter% ]     Show</msg>
to spot them.

They key choice is not great.  It's as if in coding you decided to use
v1, v2, v3... for your variable names.

Here is You_#:

<msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg>
<msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch and users with write permission on this Bug Tracker project (package instance) may do so.</msg>
<msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
<msg key="You_3">You do not have permission to reopen this refused patch, only users with write permission on the Bug Tracker package instance (project) may do so.</msg>
<msg key="You_4">You do not have permission to reopen this deleted patch, only users with write permission on the Bug Tracker package instance (project) and the submitter of the patch may do so.</msg>
<msg key="You_5">do not have permission to cancel this patch - only the submitter of the patch may do so. If you are an administrator you can however refuse the patch.</msg>
<msg key="You_6">You don't have permission to edit this patch.</msg>
<msg key="You_7">You do not have permission to unmap a bug from this patch. Only the submitter of the patch and users with write permission on the Bug Tracker package instance (project) may do so.</msg>

I would much prefer keys like: filter_by_link, perm_nomap, perm_noedit, perm_noropen_refused, etc.

Also, the semantic content is at odds with the key in a lot of them
eg:

<msg key="Fix">for version</msg>
<msg key="Fix_1">for</msg>
<msg key="Fix_2">for Bugs</msg>

The reason I think message key choice is important is that programmers and
designers, when editing an tcl or adp page, can easily get things
confused and put in the wrong key.  It can also act as a simple
guide for translators for intended semantic content of a key.

============================================================-

SOME SPECIFIC COMMENTS PER FILE:

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/lib/nav-bar.tcl?r1=1.12&r2=1.11

You assume:

  multirow append links "New [bug_tracker::conn Bug]" "${url_prefix}bug-add"

can be translated as

  multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]" "${url_prefix}bug-add"

You should translate this as something like

  set bug_label [bug_tracker::conn Bug]
  multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"

where New_Bug is "New %bug_label%"

(same problem with New Patch).

============================================================

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/lib/pagination.adp?r1=1.4&r2=1.3

Again, bad to translate fragments:

  Page with  [ @pagination_filter@ ]     Show <input type="text" name="interval_size" value="@interval_size@" /> @pretty_plural@ per page <input type="submit" value="Go" />

translated to

  #bug-tracker.Page_with_pagination# <input type="text" name="interval_size" value="@interval_size@" /> #bug-tracker.pretty_plural_per_page# <input type="submit" value="Go" />

with key

  <msg key="Page_with_pagination">Page with  [ %pagination_filter% ]     Show</msg>

============================================================

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/tcl/bug-procs.tcl?r1=1.15&r2=1.14

You tranlate an internal key here:

  workflow::case::add_log_data \
       -entry_id $entry_id \
       -key "resolution" \
       -value [db_string select_resolution_code {}]

  workflow::case::add_log_data \
       -entry_id $entry_id \
       -key "[_ bug-tracker.resolution]" \
       -value [db_string select_resolution_code {}]

(see also bug 1748)

----------------------------------------

I think the key choice here is poor.  You should attempt to preserve semantic meaning
of these phrases in the key:

return "Bug-tracker component maintainer" translated to return "[_ bug-tracker.Bug-tracker]"

return "Bug-tracker bug info" translated to return "[_ bug-tracker.Bug-tracker_2]"

return "Bug-tracker project maintainer" translated to return "[_ bug-tracker.Bug-tracker_1]"

============================================================

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/www/admin/component-ae.tcl?r1=1.10&r2=1.9

bad key choice and I am not sure why the Add and Edit words are removed for this:

if { [info exists component_id] } {
     set page_title "Edit [bug_tracker::conn Component]"
} else {
     set page_title "Add [bug_tracker::conn Component]"
}

translated to:

if { [info exists component_id] } {
     set page_title [_ bug-tracker.Edit_1]
} else {
     set page_title [_ bug-tracker.Add]
}

Edit_1 and Add are:

<msg key="Edit_1">%component_name%</msg>
<msg key="Add">%component_name%</msg>

----------------------------------------

Where did Name go in label:

    {name:text {html { size 50 }} {label "[bug_tracker::conn Component] Name"}}
  translated to
    {name:text {html { size 50 }} {label "[_ bug-tracker.Component]"}}
  with
    <msg key="Component">Component</msg>

----------------------------------------

Bad key choice:

   {help_text "You can filter by this [bug_tracker::conn component] by viisting [ad_conn package_url]com/this-name/"}
tranlated to
   {help_text "[_ bug-tracker.You]"}

============================================================

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/www/admin/index.adp?r1=1.7&r2=1.6

Convoluted logic in adp, concatenating bug/bugs with a number:

<if @components.view_bugs_url@ not nil><a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component"></if>@components.num_bugs@ <if @components.num_bugs@ eq 1>@pretty_names.bug@</if><else>@pretty_names.bugs@</else><if @components.view_bugs_url@ not nil></a></if>

<if @components.view_bugs_url@ not nil><a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#"></if>@components.num_bugs@ <if @components.num_bugs@ eq 1>@pretty_names.bug@</if><else>@pretty_names.bugs@</else><if @components.view_bugs_url@ not nil></a></if>

It would probably be better to do this as something like:

<if @components.view_bugs_url@ not nil>
  <if @components.num_bugs@ eq 1>
    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a>
  </if><else>
    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a>
  </else>
</if>

============================================================

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/www/admin/versions.adp?r1=1.6&r2=1.5

Full name created by concatenating first and last name (admittedly this is pervasive in the toolkit):

  <a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@">@past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a>

Also, title is concatenated as well.

============================================================

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/www/bug.tcl?r1=1.28&r2=1.27

Internal key translated:
{show_patch_status "open"}
to
{show_patch_status "[_ bug-tracker.open]"}

Does this work?
         set page_title "[bug_tracker::conn Bug] #$bug_number"
tranlated to:
set Bug_name [bug_tracker::conn Bug]
set page_title "[_ bug-tracker.%Bug_name% %bug_number%]"

I don't see how bug-tracker.%Bug_name% can be expected to exist but maybe I don't
understand the idiom.

Internal key translated:

  if { [string equal [workflow::action::get_element -action_id $action_id -element short_name] "edit"] } {

to

  if { [string equal [workflow::action::get_element -action_id $action_id -element short_name] "[_ acs-kernel.common_edit]"] } {

============================================================

http://cvs.openacs.org/cvs/openacs-4/packages/bug-tracker/www/patch.tcl?r1=1.9&r2=1.8

All the mode internal keys were translated.

----------------------------------------
I would suggest that the option list be returned from a function so this is not duplicated all over the place:

-options { { "[_ bug-tracker.Plain]" plain } { "[_ bug-tracker.HTML]" html } { "[_ bug-tracker.Preformatted]" pre } }

These also seem like a candidate for common keys.

----------------------------------------

mode, status internal keys translated here as well.

I fixed most of the outright bugs in the bug-tracker.

The other things I ran into were:

1. Quoting in the message catalog for tcl

   i.e. a string like
     set title "Patch \"$patch_summary\" is nice."
   being translated to
     <msg>Patch \"$patch_summary\" is nice.</msg>
   (should remove the \ quoting since its not needed).

   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).

2. Things in literal lists like

     array set names { key "Pretty" ...}

   being translated to

     array set names { key "[_bug-tracker.Pretty]" ...}

  which won't work since the _ func will not be called

  Needs to be

     array set names [list key [_bug-tracker.Pretty] ...]

  (strictly speaking the " does not need to go but "[...]"
  pretty much never needs quotes and I mostly find them annoying).

3. A lot of the acs-kernel.common_* keys had the wrong case (although
   we have keys like acs-kernel.common_edit = "Edit" which I think is
   a mistake).

The big remaining issue is that we have things like
bug_tracker::bug::workflow_create with lookups in the spec but
I don't think you want to do those lookups til runtime.

Also the parameters in bug_tracker::get_default_configurations
should be translated  (I am not sure if this gets stuffed into the db
or not).
Code within curly brackets isn't evaluated. This code
```
return { key "[_ bug-tracker.Key_Desc]" }
```
... will not process correctly. Instead, it should be
```
return {??? }
```

Prev	Home	Next
How Internationalization/Localization works in OpenACS	Up	Design Notes