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