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.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 1 Oct 2002 09:42:46 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 7 Oct 2002 15:14:18 -0000 1.2
@@ -2,104 +2,261 @@
- By Peter Marklund
+
+ By Peter Marklund
+ and Lars Pind
+
+
Introduction
This document describes how to develop internationalized OpenACS packages.
+
+
+ At this point, we've only covered things that involve the
+ message catalog: Dynamically picking a chunk of text to spit out
+ based on the locale.
+
+
+
+ Each section below consists on one part about how to write
+ new internationalized packages, and which explains the details
+ of how it works, and then another part that talks about the
+ process for internationalizing existing packages.
+
- Multilingual Text - Using the Message Catalog
+ Using the Message Catalog
+
- In this section we present the mechanisms that OpenACS provide that allows your
- OpenACS packages to handle text in multiple languages.
+ The following section will tell you how to deal with localizable
+ text in ADP files, in TCL files, and in APM Parameters.
-
- Multilingual OpenACS Parameters
+
+ Template Files (ADP Files)
- The syntax for storing multilingual pieces of text in APM parameters is identical
- to the one used for adp templates. Any message catalog keys in APM parameters should
- be surrounded by hash marks and will be replaced by the parameter::get procedure if
- it is invoked with the -localize flag. The following three examples illustrate:
+ Internationalizing templates is about replacing human readable
+ text in a certain language with intenral message keys, which
+ can then be dynamically replaced with real human language in the desired
+ locale.
+
+
+ There are 3 syntaxes to choose from: The short, the verbose,
+ and the temporary. Each offer different advantages, but
+ generally, what you want to do is use the short notation for
+ new packages and use the temporary notation for
+ internationalizing old packages, then have the APM translate
+ those into the short notation.
+
+
+
-
-
-
-
-
-
-
-
- Parameter Name
- Parameter Value
- Command used to retrieve Value
- Retrieved Value
-
-
-
-
- class_instance_pages_csv
- #dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column
- parameter::get -localize -parameter class_instances_pages_csv
- Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
-
-
- departments_pretty_name
- #departments_pretty_name#
- parameter::get -localize -parameter departments_pretty_name
- Abteilung
-
-
- ...
-
-
- departments_pretty_name
- #departments_pretty_name#
- parameter::get -parameter departments_pretty_name
- #departments_pretty_name#
-
-
-
-
+
+
+ The short:
+ #message_key#
+
+
+ The advantage of the short syntax is that it's short. It's
+ as simple as inserting the value of a variable.
+
+
-
- The value in the rightmost column in the table above is the value returned by an invocation
- of parameter::get. Not that for localization to happen you must use the -localize flag.
- The locale used for the message lookup will be
- the locale of the current request, or if there is no current request, the site-wide default locale
- (set by the parameter SiteWideLocale of the acs-lang package).
-
+
+
+ The verbose: <trn
+ key="message_key"
+ locale="locale">default
+ text</trn>
+
+
+ The verbose syntax allows you to specify a default text in
+ a certain language. This syntax is not recommended
+ anymore, but it can be convenient for development, because
+ it still works even if you haven't created the message
+ in the message catalog yet, because what it'll do is
+ create the message key with the default text from the tag
+ as the localized message.
+
+
+
+
+ The temporary:
+ <#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.
+
+
+
+
+
+
+ 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.
+
+
+
-
- Multilingual Page Templates (.adp Files)
+
+ OpenACS Parameters
+
- There are two syntaxes to choose from for doing message catalog lookups in adp templates.
- Any message catalog keys surrounded by hash marks (i.e. #message_key#) will be replaced
- with the corresponding text in the message catalog (the procedure
- lang::message::lookup is used for the lookup) using the locale of the request (given by
- ad_conn locale). If there is no message can be retrieved from the message catalog then
- a translation missing message will be used instead.
+ Some parameters contain text that need to be localized. In
+ this case, instead of storing the real text in the parameter,
+ you should use message keys using the short notation above,
+ i.e. #message-key#.
-
- The other syntax for message lookups in adp pages is <trn key="message_key">default text</trn>.
- Use the trn tag if you want to provide a default message
- in the template. The default message is in the body of the trn tag and is mandatory.
- The default message is only used if no message could be retrieved from the message catalog.
-
+
+ In order to avoid clashes with other uses of the hash
+ character, you need to tell the APM that the parameter value
+ needs to be localized when retrieving it. You do that by saying:
+ parameter::get -localize.
+
+
+
+ Here are a couple of examples. Say we have the following two
+ parameters, taken directly from the dotlrn package.
+
+
+
+
+
+
+
+
+ Parameter Name
+ Parameter Value
+
+
+
+
+ class_instance_pages_csv
+ #dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column
+
+
+ departments_pretty_name
+ #departments_pretty_name#
+
+
+
+
+
+
+ Then, depending on how we retrieve the value, here's what we get:
+
+
+
+
+
+
+
+
+ Command used to retrieve Value
+ Retrieved Value
+
+
+
+
+ parameter::get -localize -parameter class_instances_pages_csv
+ Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
+
+
+ parameter::get -localize -parameter departments_pretty_name
+ Abteilung
+
+
+ parameter::get -parameter departments_pretty_name
+ #departments_pretty_name#
+
+
+
+
+
+
+ The value in the rightmost column in the table above is the
+ value returned by an invocation of parameter::get. Note that
+ for localization to happen you must use the -localize flag.
+
+
+
+ The locale used for the message lookup will be the locale of
+ the current request, i.e. lang::conn::locale or ad_conn
+ locale.
+
+
+
+ You're responsible for creating the keys in the message
+ catalog yourself.
+
+
+