How to Internationalize a Package

Tip

+How to Internationalize a Package

Prev	Chapter�14.�Internationalization	Next

How to Internationalize a Package

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 @@ -63,14 +63,15 @@ 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 -

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

Avoiding common i18n mistakes

Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.
The automated system 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:
```
 Invitations are sent,
+ 
```

Avoiding common i18n mistakes

Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.
The automated system 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:
```
 Invitations are sent,
 when this wizard is completed and casting begins.
```
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:
```
 <#Invitations_are_sent Invitations are sent, 
 when this wizard is completed and casting begins.#>
 
```
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
@@ -155,6 +156,6 @@
 <msg key="Fix_1">for</msg>
 <msg key="Fix_2">for Bugs</msg>
```
Another example: Bug-tracker component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it should be bug_tracker_component_maintainer.
Translations in Avoid "clever" message reuse.�Translations may need to differ depending on the context in which the message appears. -
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 +
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] ...]
```

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

docs@openacs.org

View comments on this page at openacs.org