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 @@
<title></title>
<authorblurb>
- <para>By <ulink url="">Peter Marklund</ulink></para>
+ <para>
+ By <ulink url="http://www.petermarklund.com/">Peter Marklund</ulink>
+ and <ulink url="http://www.pinds.com/">Lars Pind</ulink>
+ </para>
</authorblurb>
<sect2 id="i18n-introduction">
+
<title>Introduction</title>
<para>
This document describes how to develop internationalized OpenACS packages.
</para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
</sect2>
<sect2 id="i18n-message-catalog">
- <title>Multilingual Text - Using the Message Catalog</title>
+ <title>Using the Message Catalog</title>
+
<para>
- 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.
</para>
- <sect3 id="i18n-message-catalog-params" xreflabel="Multilingual APM Parameters">
- <title>Multilingual OpenACS Parameters</title>
+ <sect3 id="i18n-message-catalog-adps" xreflabel="Internationalized Templates (ADP Files)">
+ <title>Template Files (ADP Files)</title>
<para>
- 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.
</para>
+
+ <para>
+ 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.
+ </para>
+
+ <itemizedlist>
- <table frame="all">
- <tgroup cols="4" align="center" colsep="1" rowsep="1">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <colspec colname="c3"/>
- <colspec colname="c4"/>
- <thead>
- <row>
- <entry>Parameter Name</entry>
- <entry>Parameter Value</entry>
- <entry>Command used to retrieve Value</entry>
- <entry>Retrieved Value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>class_instance_pages_csv</entry>
- <entry>#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</entry>
- <entry>parameter::get -localize -parameter class_instances_pages_csv</entry>
- <entry>Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column</entry>
- </row>
- <row>
- <entry>departments_pretty_name</entry>
- <entry>#departments_pretty_name#</entry>
- <entry>parameter::get -localize -parameter departments_pretty_name</entry>
- <entry>Abteilung</entry>
- </row>
- <row>
- <entry namest="c1" nameend="c3" align="center">...</entry>
- </row>
- <row>
- <entry>departments_pretty_name</entry>
- <entry>#departments_pretty_name#</entry>
- <entry>parameter::get -parameter departments_pretty_name</entry>
- <entry>#departments_pretty_name#</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <listitem>
+ <para>
+ The <emphasis role="strong">short</emphasis>:
+ #<emphasis>message_key</emphasis>#
+ </para>
+ <para>
+ The advantage of the short syntax is that it's short. It's
+ as simple as inserting the value of a variable.
+ </para>
+ </listitem>
- <para>
- 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).
- </para>
+ <listitem>
+ <para>
+ The <emphasis role="strong">verbose</emphasis>: <trn
+ key="<emphasis>message_key</emphasis>"
+ locale="<emphasis>locale</emphasis>"><emphasis>default
+ text</emphasis></trn>
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis role="strong">temporary</emphasis>:
+ <#<emphasis>message_key</emphasis>:<emphasis>original text</emphasis>#>
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ We recommend the short notation for new package development.
+ </para>
+
+ <sect4 id="i18n-message-catalog-adps-translate" xreflabel="Internationalizing Existing Templates (ADP Files)">
+
+ <title>Internationalizing Existing Templates (ADP Files)</title>
+
+ <para>
+ We've created a couple of special tools especially for when
+ you have an existing package that needs to be
+ internationalized.
+ </para>
+
+ <para>
+ The process involves three steps:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Run Jeff Davis' script that tries to find chunks of
+ translatable text and surround it with the temporary
+ notation mentioned above.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Go through each page by hand and manually verify that
+ the result is what you think it should be, and make the
+ necessary changes.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Above process, of course, only takes care of ADP files. You
+ need to internationalize parameters and Tcl files and other
+ parts manually.
+ </para>
+
+ </sect4>
</sect3>
- <sect3 id="i18n-message-catalog-adps" xreflabel="Multilingual Page Templates (.adp Files)">
- <title>Multilingual Page Templates (.adp Files)</title>
+ <sect3 id="i18n-message-catalog-params" xreflabel="Multilingual APM Parameters">
+ <title>OpenACS Parameters</title>
+
<para>
- 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. <emphasis
+ role="strong">#<emphasis>message-key</emphasis>#</emphasis>.
</para>
- <para>
- 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.
- </para>
+ <para>
+ 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:
+ <emphasis role="strong">parameter::get -localize</emphasis>.
+ </para>
+
+ <para>
+ Here are a couple of examples. Say we have the following two
+ parameters, taken directly from the dotlrn package.
+ </para>
+
+ <table frame="all">
+ <tgroup cols="2" colsep="1" rowsep="1">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <thead>
+ <row>
+ <entry>Parameter Name</entry>
+ <entry>Parameter Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>class_instance_pages_csv</entry>
+ <entry>#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</entry>
+ </row>
+ <row>
+ <entry>departments_pretty_name</entry>
+ <entry>#departments_pretty_name#</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Then, depending on how we retrieve the value, here's what we get:
+ </para>
+
+ <table frame="all">
+ <tgroup cols="2" colsep="1" rowsep="1">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <thead>
+ <row>
+ <entry>Command used to retrieve Value</entry>
+ <entry>Retrieved Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>parameter::get <emphasis role="strong">-localize</emphasis> -parameter class_instances_pages_csv</entry>
+ <entry>Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column</entry>
+ </row>
+ <row>
+ <entry>parameter::get <emphasis role="strong">-localize</emphasis> -parameter departments_pretty_name</entry>
+ <entry>Abteilung</entry>
+ </row>
+ <row>
+ <entry>parameter::get -parameter departments_pretty_name</entry>
+ <entry>#departments_pretty_name#</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ The locale used for the message lookup will be the locale of
+ the current request, i.e. lang::conn::locale or ad_conn
+ locale.
+ </para>
+
+ <para>
+ You're responsible for creating the keys in the message
+ catalog yourself.
+ </para>
+
</sect3>
+
</sect2>
</sect1>