By Peter Marklund and Lars Pind 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. The following section will tell you how to deal with localizable text in ADP files, in TCL files, and in APM Parameters. 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. 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 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. 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. 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#. 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.