htdocs/, www.gnucash.org and translation

[Josh Sled]

Thanks very much to Linas, we now have commits to /htdocs/trunk
prompting an update of the directory mapped to
http://www.gnucash.org/beta/ , leading to an in-situ staging environment
for the website changes.  I've been doing a bunch of work over the last
few days, in consultation with some of you, on the website structure,
and wanted to detail it here.

In short, here are some of the biggert changes:

- the main site content in www/ -- including the externals and images 
  dirs -- was moved back to the top-level.

- the accept-to-gettext language negotiation was removed; the dirs 
  themselves declare specifically what language they're in.

- many of the files were cleaned up for link-relativation.


There's been a loose decision to continue on with the gettext-based
translation, but in a modified form.  As per cstim's comments in
http://svn.gnucash.org/trac/changeset/13914 , it doesn't really work to
translate a website on a sentence-by-sentence basis.  At the same time,
it's pretty sensible to have the chrome, navigation and overall
structure be shared (i.e., identical) between the translations.  As
such, it seems like we should have something like the following [[[

  <?php include("header.phtml"); ?>
  <?php include("menu.phtml"); ?>
    // { ... in menu.phtml ...
    <li><?= _('About / News'); ?></li>
    <li><?= _('Features'); ?></li>
    // }
  <div id="body">
    <h1><?= _($title);?></h1>
    <?= _("index.phtml prose"); ?>
  </div>
  <?php include("footer.phtml"); ?>
]]], basically, the phrase content (navigation, menu text, page titles)
is gettext-ized as normal, but the bulk of the content is translated as
a unit: markup, links, structure and all.

In this way, the bulk of the site is identical for each translation, and
a conventional short-string translation effort can get an interesting
level of the website translated.  But at the same time, the translator
has the flexibility needed, even to the level of structuring the page
differently, adding sections not present in the default language, using
different images, &c.

I've started to take this approach with the de/ and fr/ dirs (the fr one
unfortunately not yet committed).  The de.po has been started by cstim,
and the fr.po I started to glean from the wholly-translated copy of the
old website (and a bit of help from my french-familiar fiancée ;).


On the implementation side, you'll see that a translation consists of
the following structure:

htdocs/trunk/
|-- index.phtml
|-- features.phtml
[... other content pages ...]
|-- po/
  |-- de.po
|-- lang.php
|-- de/
  |-- .htaccess
  |-- LC_MESSAGES
    |- gnucash-htdocs.mo
  |-- local.php
  |-- index.phtml -> ../index.phtml
  |-- features.phtml -> ../features.phtml
  [... symlinks to other content pages ...]
|-- fr/
  [same structure as above]

The translated-dir content is a set of symlinks to the actual content
pages at the top-level.

The .htaccess files serve to enable symlink traversal at the apache
httpd level.

The key feature of a translation is the `local.php` file.  The pages now
immediately include the `local.php` file, which sets up the
directory-local variables $locale and $top_dir.  From this first one,
especially, gettext is configured.  (Hopefully in the future, we can
derive both $locale and $top_dir from the path name itself, but that's
in the future. ;)

(In the future, too, we might want to pre-render all enumerations of
these pages on commit or manually.  But what we have presently is
working fine, so I'm not too keen on more upheaval right now.)


The biggest things left undone w.r.t. i18n presently are:
  - conversion of fr/, nl/, pt_PT/ into "new-style" 
  - changing the page bodies into
    <?= _("index.phtml body prose"); ?>
  - handling news translations


NOTE that this doesn't presently work *on* www.gnucash.org; I've a
seperate mail to Linas about what I think a cause (and hopefully fix)
is. :/  In the mean time, it does seem to work at
http://asynchronous.org/tmp/www.gnucash.org/ , at least for de/ .

Thoughts?

-- 
...jsled
http://asynchronous.org/ - `a=jsled; b=asynchronous.org; echo ${a}@${b}`