Index: openacs-4/packages/acs-admin/www/apm/version-i18n-index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n-index.adp,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-admin/www/apm/version-i18n-index.adp 23 Oct 2002 11:38:59 -0000 1.1 +++ openacs-4/packages/acs-admin/www/apm/version-i18n-index.adp 29 Oct 2002 08:14:24 -0000 1.2 @@ -1,21 +1,49 @@ -@page_title@ -@context_bar@ + @page_title@ + @context_bar@ +

Import/Export Messages

+ -

-

  • Export (dump) messages from database to xml catalog files
    • -

    +

    Internationalize Package

    -

    -

  • Import messages from xml catalog files to database (overwrites texts in the database)
    • -

    - -

    -

  • Import messages from old tcl-based catalog files (.cat files) to database (overwrites texts in the database)
    • -

    + + + +

    Convert Message Catalog to New Format

    + + +     \ No newline at end of file Index: openacs-4/packages/acs-admin/www/apm/version-i18n-index.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n-index.tcl,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-admin/www/apm/version-i18n-index.tcl 23 Oct 2002 11:38:59 -0000 1.1 +++ openacs-4/packages/acs-admin/www/apm/version-i18n-index.tcl 29 Oct 2002 08:14:24 -0000 1.2 @@ -6,11 +6,21 @@ @cvs-id $Id$ } { version_id:integer,notnull +} -properties { + page_title + context_bar + num_cat_files } -db_1row package_version_info "select pretty_name, version_name from apm_package_version_info where version_id = :version_id" +db_1row package_version_info { + select package_key, pretty_name, version_name + from apm_package_version_info + where version_id = :version_id +} set page_title "Manage Internationalization of $pretty_name $version_name" set context_bar [ad_context_bar $page_title] +set num_cat_files [llength [glob -nocomplain "[acs_package_root_dir $package_key]/catalog/*.cat"]] + ad_return_template Index: openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.adp,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.adp 9 Oct 2002 16:03:50 -0000 1.1 +++ openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.adp 29 Oct 2002 08:14:24 -0000 1.2 @@ -5,5 +5,5 @@ @processing_html_result@

    -@proceed_label@ + => @proceed_label@

    Index: openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.tcl,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.tcl 11 Oct 2002 17:57:47 -0000 1.3 +++ openacs-4/packages/acs-admin/www/apm/version-i18n-process-2.tcl 29 Oct 2002 08:14:24 -0000 1.4 @@ -38,7 +38,7 @@ set text_replacement_list [lindex $adp_text_result_list 0] set text_untouched_list [lindex $adp_text_result_list 1] - append processing_html_result "Replaced [llength $text_replacement_list] texts:
    " + append processing_html_result "Replaced [llength $text_replacement_list] texts:
    " foreach text_replacement $text_replacement_list { append processing_html_result "replaced text \"[lindex $text_replacement 1]\" using key [lindex $text_replacement 0]
    " } @@ -84,7 +84,7 @@ if { [llength $files] > 0 } { # There are no more files to process so present a link back to the i18n page for this version set proceed_url "version-i18n-process?${proceed_url_export_vars}" - set proceed_label "Process next adp file" + set proceed_label "Process next adp file" } else { # There are more files to process. This means we are doing text replacements Index: openacs-4/packages/acs-admin/www/apm/version-i18n-process.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n-process.adp,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-admin/www/apm/version-i18n-process.adp 11 Oct 2002 17:57:47 -0000 1.2 +++ openacs-4/packages/acs-admin/www/apm/version-i18n-process.adp 29 Oct 2002 08:14:24 -0000 1.3 @@ -2,9 +2,9 @@ @page_title@ @context_bar@ -Choose which message keys to use for file @file@. If you leave a message key blank no replacement will be done -and the corresponding text in the adp will be left untouched. The text that is actually replaced is bold and highlighted -with a yellow background in the "Text to Replace" column. +

    + Current File: @file@ +

    @@ -31,3 +31,14 @@
    + +

    Instructions

    + +

    + Choose which message keys to use for this file. If you leave a + message key blank no replacement will be done and the corresponding + text in the adp will be left untouched. The text that is actually + replaced is bold and highlighted with a yellow background in the + "Text to Replace" column. +

    + Index: openacs-4/packages/acs-admin/www/apm/version-i18n-process.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n-process.tcl,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-admin/www/apm/version-i18n-process.tcl 11 Oct 2002 17:57:47 -0000 1.2 +++ openacs-4/packages/acs-admin/www/apm/version-i18n-process.tcl 29 Oct 2002 08:14:24 -0000 1.3 @@ -32,6 +32,8 @@ # Process one adp at a time interactively set file [lindex $files 0] +set full_file_name "[acs_root_dir]/$file" + set adp_report_list [lang::util::replace_adp_text_with_message_tags "[acs_root_dir]/$file" report] set adp_replace_list [lindex $adp_report_list 0] set adp_no_replace_list [lindex $adp_report_list 1] Index: openacs-4/packages/acs-admin/www/apm/version-i18n.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n.adp,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-admin/www/apm/version-i18n.adp 24 Oct 2002 09:07:12 -0000 1.6 +++ openacs-4/packages/acs-admin/www/apm/version-i18n.adp 29 Oct 2002 08:14:24 -0000 1.7 @@ -2,114 +2,162 @@ @page_title@ @context_bar@ -
    - -

    -@file_type_filter@ +

    + @file_type_filter@

    -

    -@pre_select_filter@ | @status_filter@ +

    + @pre_select_filter@ | @status_filter@ (?)

    -

    -

    -
    +

    Instructions

    -

    Important Instructions

    - -

    The I18N status of adp 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\#). + Here's the process for internationalizing a package:

    -

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

    +
      +

      +

    1. + Replace text with tags in ADP files: Run above process + for ADP files with only the first action checked. +
      2. +

      +

      +

    2. + Manually check ADP files: Go through the ADP files and + check that the <\#...\#>'s are where they should be. +
      3. +

      +

      +

    3. + Manually check Tcl files: Go through the Tcl files, and + replace any localizable text with the <\#...\#> notation. +
      4. +

      +

      +

    4. + Replace tags with keys and insert into catalog: Run this + action for both ADP files and Tcl files, one after another. +
      5. +

      +

    Actions to take on adp files

    +

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

    Replacing text with tags

    +

    -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). + 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 "Forum \@forum_name\@" untouched. What you should do then is to edit the corresponding -adp file and manually replace that text with something like "<#Forum Forum#> \@forum_name\@" (to save you from too much typing you may use the shorthand <#_ Forum#>, 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". + 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 "Forum \@forum_name\@" untouched. What you should do then + is to edit the corresponding adp file and manually replace that text + with something like "<#Forum Forum#> \@forum_name\@" (to save you + from too much typing you may use the shorthand <#_ Forum#>, 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: + 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, look for alt attributes with literal text
 find -iname '*.adp'|xargs egrep -i '<img'
 # List submit buttons, look for text in the value attribute 
 find -iname '*.adp'|xargs egrep -i '<input[^>]*type="?submit'
    -

    Replace tags with keys and insert into catalog

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

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

    +

    Dealing with tcl files

    +

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

    @@ -124,22 +172,30 @@

    -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 in it you may choose to turn the whole text into one message in the -catalog. If you choose this option you cannot use the message tag syntax but rather you must -manually replace the text with an invocation of the message lookup procedure (the underscore -procedure) as well as manually insert the message into the catalog file (you should -check that your message key is unique when you do this). Here is an example from dotlrn: + 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 in it you may choose to turn the whole text into one + message in the catalog. If you choose this option you cannot use the + message tag syntax but rather you must manually replace the text + with an invocation of the message lookup procedure (the underscore + procedure) as well as manually insert the message into the catalog + file (you should check that your message key is unique when you do + this). Here is an example from dotlrn:

    -The code +

    + The code +

    + 
     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 manually by: +

    + was replaced manually by: +

     set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] 
@@ -148,15 +204,17 @@
 ad_return_complaint 1 [_ [ad_conn locale] dotlrn.class_may_not_be_deleted "" $msg_subst_list]
    -and the following line was added to the catalog file: +

    + and the following line was added to the catalog file: +

     _mr en_US dotlrn.class_may_not_be_deleted {Error: A %subject% must have no %class_instances% to be deleted}

    -When we were done going through the tcl files we ran the -following commands to check for mistakes: + When we were done going through the tcl files we ran the following + commands to check for mistakes: 

    @@ -171,24 +229,53 @@

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

    Checking the Consistency of the Catalog File

    -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: + 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. The script will run its -test on the en_US xml catalog file. +

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

    + +

    Help

    + +

    The I18N status of adp 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. +

    + Index: openacs-4/packages/acs-admin/www/apm/version-i18n.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/version-i18n.tcl,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-admin/www/apm/version-i18n.tcl 23 Oct 2002 11:38:59 -0000 1.3 +++ openacs-4/packages/acs-admin/www/apm/version-i18n.tcl 29 Oct 2002 08:14:24 -0000 1.4 @@ -85,7 +85,7 @@ -widget checkbox \ -label $action_label \ -options {{{Replace text with tags} replace_text} {{Replace tags with keys and insert into catalog} replace_tags}} \ - -values {replace_text replace_tags} \ + -values {replace_text} \ -section action_section } else { # TCL files