@file_type_filter@
@pre_select_filter@ | @status_filter@ (?)
Here's the process for internationalizing a package:
An important piece of advice when doing message catalog conversion is to replace phrases rather than words with message catalog lookups. The reason for this is that different languages have very different grammar. An example of this is that some languages don't have prepositions.
The last two checkboxes in the form above let you choose which of the two available scripts to run on the selected adp files. You have to choose at least one of these actions, by default both are selected and for almost all cases this is the setting that we recommend. When translating the dotlrn package we first ran through all adp files with both actions. For each adp file, we looked at the untouched texts on the result page and manually inserted <#key text#> tags in the adp where appropriate. When we were done with this run-through we then ran the action "Replace tags with keys and insert into catalog" to remove the temporary tags from the adp:s.
To the best of our knowledge there is no harm in running those actions multiple times on files. Before an adp file is modified it will be backed up to a file with the name of the original file with the ending .orig appended to it (i.e. www/a-file.adp is backed up to www/a-file.adp.orig). However if such an .orig file already exists no backup is done.
If the adp status for a file shows 0 translatable texts, then the "Replace texts with tags" action will do nothing. Likewise, if the adp status shows 0 tags then "Replace tags with keys and insert into catalog" action will have no effect.
If you select "Replace text with tags" then for each adp file a script will attempt to replace translatable text with temporary <#message_key text#> tags. You will have the opportunity to edit the message keys to use. You will also be able to indicate when a piece of text should be left untouched (since it should not be subject to translation, for example Javascript code).
Any pieces of text that our script finds that it could not automatically extract, for example pieces of text with embedded adp variables (i.e. \@var_name\@), will be listed on the result page. Make sure to take note of these texts and translate them manually. Suppose for example that our script tells you that it left the text "Manage forum \@forum_name\@" untouched. What you should do then is to edit the corresponding adp file and manually replace that text with something like "<#manage_forum Manage forum \@forum_name\@#>" (to save you from too much typing you may use the shorthand <#_ Manage forum \@forum_name\@#>, an underscore key will result in the script auto-generating a key for you based on the text). After you have made all such manual edits you can simply run the second action labeled "Replace tags with keys and insert into catalog".
Note: running this action will not find translatable text within HTML or adp tags on adp pages (i.e. text in alt tags of images), nor will it find translatable text in tcl files. Such texts will have to be found manually. If those texts are in adp files they are best replaced with the <#message_key text#> tags that can be extracted by the action described below. Here are some commands that we used on Linux to look for texts in adp pages not found by the script:
# List image tags with alt attributes, look for alt attributes with literal text find -iname '*.adp'|xargs egrep -i '<img.*alt=' # List submit buttons, look for text in the value attribute find -iname '*.adp'|xargs egrep -i '<input[^>]*type="?submit'
If selected, this action will be executed after the "Replace text with tags" action. It will replace any occurence of the temporary <#message_key text#> tags with \#message_key\# lookups in the adp files and insert the corresponding keys and messages into the en_US catalog file for the package.
Entries for the extracted messages will be added to the en_US catalog file only if they do not already exist in that file. If the messages don't contain the package key prefix this prefix will be added before insertion into the message catalog.
The message tags are processed from the adp:s in the order that they appear. If the key of a message tag is already in the catalog file then the message texts will be compared. If the message texts in the tag and in the catalog file are identical then no insertion is done to the catalog file. If they differ it is assumed that the new message should be inserted into the catalog file but with a different key. In this case a warning is issued in the log file and an integer is appended to the message key to make it unique before insertion into the catalog file is done.
When internationalizing the tcl files in the dotlrn package we noticed that translatable texts are often found in page titles, context bars, and form labels and options. Many times the texts are enclosed in double quotes. We used the following grep commands on Linux to highlight translatable text in tcl files for us:
# Find text in double quotes find -iname '*.tcl'|xargs egrep -i '"[a-z]' # Find untranslated text in form labels, options and values find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$' # Find text in page titles and context bars find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#' # Find text in error messages find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'
You may mark up translatable text in tcl library files and tcl pages with temporary tags (on the <#key text#> syntax mentioned previously). If you have a sentence or paragraph of text with variables and or procedure calls in it you should in most cases try to turn the whole text into one message in the catalog. In those cases, follow these steps:
The variable values in the message are usually fetched with upvar, here is an example from dotlrn:
ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name]
must have no[parameter::get -parameter class_instances_pretty_plural] to be deleted"
was replaced by:
set subject [parameter::get -localize -parameter classes_pretty_name] set class_instances [parameter::get -localize -parameter class_instances_pretty_plural] ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted]
This kind of interpolation also works in adp files where adp variable values will be inserted into the message.
Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes:
set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name]
class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]
ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted $msg_subst_list]
When we were done going through the tcl files we ran the following commands to check for mistakes:
# Message tags should usually not be in curly braces since then the message lookup may not be
# executed then (you can usually replace curly braces with the list command). Find message tags
# in curly braces (should return nothing, or possibly a few lines for inspection)
find -iname '*.tcl'|xargs egrep -i '\{.*<#'
# Check if you've forgotten space between default key and text in message tags (should return nothing)
find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
# Review the list of tcl files with no message lookups
for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done
When you feel ready you may run the action "Replace tags with keys and insert into catalog" on the tcl files that you've edited to replace the temporary tags with calls to the message lookup procedure.
This section describes how we checked 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 done with the underscore procedure. The script 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 on en_US xml catalog files.
Clicking on the "Show I18N status of files" link above will display three counts for each adp file - the number of potential translatable text messages, the number of temporary tags (on the syntax <#message_key text#>), and the number of message key lookups in the file (i.e. occurencies of \#message_key\#).
A fully translated adp must have 0 tags, it typically has 0 or only a few texts deemed translatable by our script and any number of message key lookups (the last count). Our script sometimes considers for example Javascript to be translatable, but don't worry - you will have the opportunity to tell it to leave such texts untouched.