Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 7 Oct 2002 15:14:18 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 18 Nov 2002 18:09:13 -0000 1.3
@@ -92,13 +92,16 @@
The temporary:
- <#message_key:original text#>
+ <#message_key original text#>
This syntax has been designed to make it easy to
internationalize existing pages. This is not a syntax that
stays in the page. As you'll see later, it'll be replaced
- with the short syntax by a special feature of the APM.
+ with the short syntax by a special feature of the APM. You
+ may leave out the message_key by writing an underscore (_)
+ character instead, in which case a message key will be
+ auto-generated by the APM.
@@ -108,61 +111,11 @@
We recommend the short notation for new package development.
-
-
- Internationalizing Existing Templates (ADP Files)
-
-
- We've created a couple of special tools especially for when
- you have an existing package that needs to be
- internationalized.
-
-
-
- The process involves three steps:
-
-
-
-
-
-
- Run Jeff Davis' script that tries to find chunks of
- translatable text and surround it with the temporary
- notation mentioned above.
-
-
-
-
-
- Go through each page by hand and manually verify that
- the result is what you think it should be, and make the
- necessary changes.
-
-
-
-
-
- Visit the package in the package manager and run the
- script that finds the temporary notation and replaces it
- with either one of the permanent notations mentioned
- above, namely the short or the verbose.
-
-
-
-
-
-
- Above process, of course, only takes care of ADP files. You
- need to internationalize parameters and Tcl files and other
- parts manually.
-
-
-
- OpenACS Parameters
+ APM Parameters
Some parameters contain text that need to be localized. In
@@ -259,4 +212,213 @@
+
+
+
+ Dates, Times, and Numbers
+
+
+ Let's deal with dates and times first. The way it works is as follows:
+
+
+
+
+
+
+ Get the date in ANSI format from the database (YYYY-MM-DD
+ HH24:MI:SS, the time portion is optional). Name the column
+ in the SQL statement something that ends in
+ "_ansi", such as
+ "posting_date_ansi". Example:
+ to_char(posting_date, 'YYYY-MM-DD
+ HH24:MI:SS') as posting_date_ansi
+
+
+
+
+
+ Use the Tcl command "lc_time_fmt" to format the
+ date in pretty format. There are a number of standard,
+ localizable formats to choose from (see below). Example:
+ set posting_date_pretty [lc_time_fmt
+ $posting_date_ansi "%q"]
+
+
+
+
+
+ Use the "*_pretty"-version in your ADP page.
+
+
+
+
+
+
+ Here's the list of standard date and time formats to choose
+ from:
+
+
+
+
+
+
+ %c: Long date and time (Mon November 18, 2002 12:00 AM)
+
+
+
+
+
+ %x: Short date (11/18/02)
+
+
+
+
+
+ %X: Time (12:00 AM)
+
+
+
+
+
+ %q: Long date without weekday (November 18, 2002)
+
+
+
+
+
+ %Q: Long date with weekday (Monday November 18, 2002)
+
+
+
+
+
+
+ If the abbreviations seem a bit strange, it's because they
+ are. Most of them are standardized (see man
+ strftime for example). %q and %Q are our
+ proprietary additions, and 'q' was just about the only letter
+ left in the alphabet.
+
+
+
+ The command 'lc_fmt_time' allows you to pass in a specific date
+ and time format as well, but please don't, because the whole
+ point is to make it possible for administrators to change date
+ and time formats site-wide based on locales.
+
+
+
+ Numbers are very easy to format. Just say
+ lc_numeric $value, and it'll
+ format the number using the appropriate decimal point and
+ thousand separator for the locale.
+
+
+
+
+
+
+
+
+ Internationalizing Existing Packages
+
+
+ Page Files (ADP and Tcl Files)
+
+
+ We've created a couple of tools especially for
+ internationalizing the pages of existing packages. The tools can
+ be accessed from the "Manage Internationalization"
+ linked from the package manager page for a package.
+
+
+
+ The process consists of four steps:
+
+
+
+
+
+
+ Replace text with tags:
+ This is an automated process, which will try to
+ automatically locate chunks of translatable text,
+ auto-generate a reasonable message key, and surround the
+ text with the temporary <#...#> notation mentioned
+ above.
+
+
+
+
+
+ Manually verify each ADP
+ file. If necessary, you can add additional
+ <#...#> tags, or you can move or remove the ones set
+ by the automated step.
+
+
+
+
+
+ Manually mark up Tcl
+ files, marking up translatable text with the
+ <#...#> notation.
+
+
+
+
+
+ Replace tags with keys:
+ This is an automated process, which will replace the
+ temporary <#...#> notation in both ADP and Tcl files
+ with the appropriate notation for the type of file, and
+ store the text in the message catalog. You need to run the
+ process twice, once for ADP files, and once for Tcl files.
+
+
+
+
+
+
+ Replace Text With Tags Step
+
+
+ When you run this step, any modified files are backed up in
+ a file with a ".orig" suffix. Those files are
+ never overwritten, though, so the .orig file will always be
+ the original page file, not the second-to-last file. Running
+ this action multiple times is harmless.
+
+
+
+ The system will auto-generate suggested message keys.
+
+
+
+ ... (WRITE MORE HERE!)
+
+
+
+
+
+ Replace Tags With Keys Step
+
+
+
+
+
+
+
+
+
+
+ Next step is to internationalize parameters that contain
+ localizable text. See the section .
+
+
+
+
+
+