Index: openacs-4/packages/acs-core-docs/www/i18n-convert.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.adp,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/i18n-convert.adp 25 Apr 2018 08:38:27 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/i18n-convert.adp 2 Mar 2019 19:30:04 -0000 1.4.2.1
@@ -1,5 +1,5 @@
-
Replace all text with temporary message
-tags. From
Replace the temporary message tags in ADP
-files. From the same
Replace human-readable text in Tcl files with temporary
-tags. Examine all of the Tcl files in the packages
+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
@@ -67,7 +67,7 @@
Replace the temporary message tags in Tcl
-files. Repeat step 2 for Tcl files. Here is the
+files. Repeat step 2 for Tcl files. Here is the
example Tcl file after conversion:
-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 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
/acs-admin/apm/
, select a package and then
+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
@@ -33,7 +33,7 @@
them key by key.Convert ADP ...
page in /acs-admin/apm
as in the last step, repeat
+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
@@ -42,7 +42,7 @@
an xml file.
set title [_ simulation.admin_title]
set context [list [list . [_ simulation.SimPlay]] \
@@ -76,9 +76,9 @@
[_ simulation.lt_Messages_for_role_pre]]
lc_numeric $value
, which formats the number
using the appropriate decimal point and thousand separator for the
locale.
-Internationalizing Forms. When coding +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
+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 @@ -148,19 +147,19 @@
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,
+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, @@ -235,14 +234,14 @@ </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:
+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 @@ -253,7 +252,7 @@ \@past_version.maintainer_first_names\@ \@past_version.maintainer_last_name\@</a>
-Avoid unnecessary duplicate keys. When +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 @@ -267,13 +266,14 @@
Don't internationalize internal code -words. Many packages use code words or key words, +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.
For example, the original code is
workflow::case::add_log_data \ +be used in a switch or if statement. Don't change these.For example, the original code is
+workflow::case::add_log_data \ -entry_id $entry_id \ -key "resolution" \ - -value [db_string select_resolution_code {}]This is incorrectly internationalized to
workflow::case::add_log_data \ + -value [db_string select_resolution_code {}]This is incorrectly internationalized to
workflow::case::add_log_data \ -entry_id $entry_id \ -key "[_ bug-tracker.resolution]" \ -value [db_string select_resolution_code {}]But
resolution
is a keyword @@ -284,7 +284,7 @@ {show_patch_status "[_ bug-tracker.open]"}
-Fix automatic truncated message keys. The +Fix automatic truncated message keys. The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:
@@ -309,19 +309,19 @@
should be bug_tracker_component_maintainer
.
Translations in Avoid "clever" message -reuse. Translations may need to differ depending on +reuse. Translations may need to differ depending on the context in which the message appears.
-Avoid plurals. Different languages create +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
+Quoting in the message catalog for +tcl. Watch out for quoting and escaping when editing +text that is also code. For example, the original stringset 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:
@@ -331,7 +331,7 @@ output).
-Be careful with curly brackets. Code +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