[Pmwiki-users] Internationalization structure

[Patrick R. Michaud]

After having a night to sleep on it and some time to think about it,
I finally came to the conclusion that many others are correct and
that arrays are indeed the way to go for performing language translations.
And, for better or worse, I went ahead and grafted the translation 
routines directly into the pmwiki.php codebase, and hopefully this won't
scare off too many newbie PHP programmers and WikiAdministrators...

I've also converted all of the existing language files to use the new 
translation system, and renamed them from lang-xx.php to i18n-xx.php, 
where "xx" is the appropriate language identifier.  The previous 
lang-xx.php files will still work but should probably be deprecated 
in favor of the new system.

The translation system I finally adopted adds a new syntax to the $...Fmt
variables.  A $...Fmt variable can now have a string of the form
"$[some phrase]" in it, which means to use a translation of "some phrase"
if one is available, otherwise simply display "some phrase" without
the $[...].

The phrase translations are held in the $XL array, which is indexed
by a language identifier (such as "fr" for French) and a phrase to be
translated.  For example,

  $XL['fr']['Edit Page'] = 'Modifier la page';

specifies "Modifier la page" as the French translation for "Edit Page".
Then, a format variable can make use of this translation by doing
something similar to

  $PageHeaderFmt = 
    "...  <a href='\$ScriptUrl?action=edit'>$[Edit Page]</a> ...";

and the $[Edit Page] is substituted with the corresponding phrase from 
the $XL array if one is available, otherwise it just uses "Edit Page".
Note that only things inside of $[...] are translated, thus old
$Fmt variable values continue to work exactly as they always have.

The languages to be used for translation are specified by the 
$XLLangs array.  Thus,

  $XLLangs=array('fr','en');

says to use the 'fr' phrase translation if it is available, otherwise
use the 'en' translation, otherwise use the phrase itself as it appears
within the $[...].  This allows more sophisticated translation sets:

  $XLLangs=array('de_AT','de','fr','en');

which would prioritize phrase translations into Austrian German, German,
French, English, and finally the phrase itself if none of those languages
has a translation defined for the phrase.

PmWiki defines a helper function called XLSDV($lang,$phrases) to assist
with populating the $XL array.  The $lang argument is the language
identifier, the second argument is an array of phrases to be added to
the existing translation table for $lang.  Thus, one can quickly create
add translations for a set of phrases by doing something like the
following (excerpted from the current i18n-fr.php file):

  XLSDV('fr',array(
    'Main/SearchWiki' => 'PmWikiFr/RechercheWiki',
    'SearchWiki' => 'RechercheWiki',
    'Edit Page' => 'Modifier la page',
    'Page Revisions' => 'Version de la page',
  # 'redirected from' => '',
    'PmWiki/WikiHelp' => 'PmWikiFr/Aide',
    'WikiHelp' => 'Aide',
    'Page last modified on $LastModified' => 
      'Page mise ? jour le $LastModified',
  # ...
  ));

If $XLLangs selects the 'fr' language, then anytime one of these
phrases appears in "$[...]" in a $...Fmt variable the translation 
to French is performed.  Note that in the table above "redirected from" 
doesn't have a translation yet and so it has been commented out
but left in by the author in case someone comes up with a translation
in the future).

pmwiki.php sets $XLLangs to array('en') by default.  Since
the keys themselves are generally in English, the 'en' translation
array is largely empty except for a few shortcut translations used
by the search.php and upload.php scripts.  

If this all seems somewhat confusing--I think it makes much more sense 
once you take a look at the code and one of the i18n-xx.php files.

As always, your comments, feedback, and suggestions are greatly
desired.

Pm