first outline (was: clickable language selection)

[André Malo <nd...@perlig.de>]

* Lars Eilebrecht wrote:

>> Long time ago I've build a kind of "Forced Content Negotiation". Main goal:
>> documents are negotiated until the user changes the language. That is done
>> by putting the language into the url path then and forcing the response to
>> be in that language (using mod_rewrite).
> 
> Would you mind posting the config details.

Of course ;-)
First I had to search my archives and find the old stuff and then puzzle 
out, how to make it work with the 2.x docs.

ok. short story: I've built a working system with the current HEAD, you can 
browse it at <http://test.perlig.de/manual/> (the .ja versions are a bit 
bogus (something on my system doesn't build them correctly).
Note, that the language lists are always present on top and bottom of the 
page(s).

Long story follows below.

At this point a credit: much thanks to Kess for her tips to make it work.
;-)

-----------

There were two main problems to solve:

1st - creating the rewrite stuff.

This was the easiest part. You'll find it attached to this mail 
(rewrite-lang.txt). It's a bit tricky, because the virtual /$lang/ branch 
acts as a "directory". Therefore Some trailing slash redirects have to be 
done by mod_rewrite.
Note: the attached rewrite rules/conds assume, that the docs are in a 
/manual/ directory which is placed under DocumentRoot.

In order to make it work, all available languages have to be "registered" 
in a rewrite map. It maps the language token to the real file extension 
(after .html). An example map is attached (lang2ext.txt). The rewriting 
will only be done, if the URL contains a "registered" language on the right 
place. (/manual/$lang/) for example. It will do some sanity checks and 
force to show the requested language, if it exists. Otherwise 
mod_negotiation will do its normal work.

For an explanation of the "nested language" rule, see the "caveats" section 
below.

> But how does the user change the language in the first place?
> If we provide some kind of pull down menu on the page the page
> gets 'dynamic' as we may have a varying list of available languages
> for a specific resource.

I'd also prefer static links.
That will lead us immediately to the 2nd problem:

How to inject the filename and the variant list into the transformation 
process?

We've considered a bunch of variants and the following won:

We maintain "metafiles". These files have to exist for every document (one 
metafile for all variants of a document). The files contain information 
about the available variants, the file(base)name and the path within the 
docs tree. The advantage is, that the files can be maintained automatically 
by the build process. Currently it's done by a perl script that keeps the 
metafiles up to date (<http://test.perlig.de/manual/build/metafile.pl>).

You'll find a sample metafile at the end of the script.

It will be called, before the transformation process starts. I've put my 
current build.xml also online, at: 
<http://test.perlig.de/manual/build/build.xml> (you may need to view the 
source...). The interesting section is <apply> within the xslt target.
It should be noted, that the metafiles have to be checked in. Otherwise the 
dependency checking may fail.

Of course the metafiles have to be invoked into the build process. I 
couldn't find a way to inject the current file name from ant to the xslt 
transformation. If there is one, we should use it.
Currently I referenced the particular metafile from every document. A new 
attribute for the root elements "metafile" was added. it contains the name 
of the metafile, that must exist in the same directory then.

You'll find the whole patch against the source files (*.xml*, *.xsl, *.css) 
at: <http://test.perlig.de/manual/build/trans.diff> (~ 160 K)

(It applies to 2.1 (HEAD) and has to be backported to 2.0)

------------

CAVEATS

It works fine at the first view, but has (of course ;-) some caveats:

- if someone forces a language or switches between languages, all 
"background" ressources will be reloaded, since they are available under a 
new URL. (i.e., manual.css is accessable via 
/manual/($lang/)?style/css/manual.css).

- we provide also a lot of front ressources under different URLs (i.e., 
/manual/sitemap.html is often effectively the same as 
/manual/en/sitemap.html). This may blow up proxy caches and search engine 
indexes.

- also related to the points above: If we use static links (vs. we could 
correct them via SSI) for switching between the languages, we get URLs like
/manual/en/de/<stuff> (if we are within the en-branch and switch to de). 
This is currently handled by a redirect (301) to /manual/de/<stuff>.

These are all acceptable, I think.

- the last, but *critical* caveat is: the presented solution currently only 
works on filesystems, that treat '/' as filesystem root (i.e. *x) -- 
mod_rewrite is totally broken on other systems (there is some confusion 
between filesystem root and url root. AFAICS it needs some bigger rewrite 
(sic! ;-).

  * server context rules don't work anyway
  * directory context rules work not always

So currently it can't be distributed that way. (yes, mod_rewrite should be 
fixed, but it's probably too late for 2.0.44. It should be discussed in 
detail elsewhere.)
However, it took some time and workarounds to build directory context based 
rewrite rules that work under win32 as expected. You'll find them attached 
as rewrite-lang-win.txt (directly from my machine).

So, if we decide to take the solution and want to distribute it with 
2.0.44, we may include this into the win32, netware (and os/2?) configs.

*uff*

I hope, I didn't forget anything.
However, if there are any questions, please ask.

nd
-- 
Da fällt mir ein, wieso gibt es eigentlich in Unicode kein
"i" mit einem Herzchen als Tüpfelchen? Das wär sooo süüss!
 
                                 -- Björn Höhrmann in darw