Index: openacs-4/packages/acs-core-docs/www/i18n-convert.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.html,v diff -u -N -r1.26.2.10 -r1.26.2.11 --- openacs-4/packages/acs-core-docs/www/i18n-convert.html 10 Jun 2016 07:35:08 -0000 1.26.2.10 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.html 11 Jun 2016 08:44:02 -0000 1.26.2.11 @@ -72,7 +72,7 @@ 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

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:

      <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
@@ -110,7 +110,7 @@
   </if>
 
 <if @components.view_bugs_url@ not nil>
-<a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">
+<a href="@components.view_bugs_url@" title="#­bug-tracker.View_the_bug_fo_component#">
 </if>
 @components.num_bugs@ 
 <if @components.num_bugs@ eq 1>
@@ -124,12 +124,12 @@
 </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>
+    <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>
+    <a href="@components.view_bugs_url@" title="#­bug-tracker.View_the_bug_fo_component#">#­bug-tracker.N_bugs#</a>
   </else>
 </if>

  • Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:

    Original code:

    multirow append links "New [bug_tracker::conn Bug]"

    Problematic conversion:

    multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"

    Better conversion:

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

    ... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.

    In this example of bad i18n, full name is 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@">
+multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"

    ... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.

    In this example of bad i18n, full name is 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>

  • Avoid unnecessary duplicate keys. When phrases are exactly the same in several places, use a single key.

    For common words such as Yes and No, you can use a library of keys at acs-kernel. For example, instead of using