[mapserver-dev] documentation localization and svn structure

[Lars Lingner]

Howard Butler schrieb:
> 
> On Apr 1, 2009, at 2:22 PM, Lars Lingner wrote:
> 
>> Hello list,
>>
>> I would like to know how the structure in the repository should be
>> organized in regard to future translations. At
>> http://svn.osgeo.org/mapserver/trunk/docs/ is the English documentation
>> and one idea is to use an subdirectory for each language:
>>
>> ...trunk/docs/de
>> ...trunk/docs/fr
>> etc.
>>
>> So should I just create the directory? Are there objections or other
>> ideas?
> 
> Though not well documented, sphinx supports the use of language suffixes
> on document names so that Apache can send either the  browser-requested
> document or the fallback (en-us in our case).  I don't remember the name
> of the apache module that needs to be configured to do this, and we
> haven't actually tried to do this, but it is theoretically possible.
> 
> Instead of trunk/docs/de it would just be
> trunk/docs/mapfile/class_de.txt or trunk/docs/mapfile/layer_de.txt  As I
> said, however, we need a functional test of this to make sure it can
> actually work for us :)


I was playing around with Sphinx, but couldn't get the language suffixes
to work. Instead I found a way to handle the docs as follow:

#some "global" files and directories
...trunk/docs/_static
...trunk/docs/_templates
...trunk/docs/{conf.py,labels.py,Makefile)
#and the documentation separated in <language>-directories
...trunk/docs/en/{cgi,community,development,...)
...trunk/docs/de/{cgi,community,development,...)

I modified the Makefile, so that for every language the html/latex/etc
code output is generated.
The output will be placed in ../build/en/{html, latex, labels,...} the
german output goes in ../build/de/{html, latex, labels,...}. Other
languages will be handled the same way.

The generated code can be served by the webserver. Wouldn't it be
possible to use mod_rewrite to keep the current urls but get the content
from an <lang>-subdirectory?

In the layout template (_templates/layout.html) I added code so the user
can switch the language.
If you want to get a first impression you can take a look here:

http://www.lingner.eu/docs/umn/build/en/html/mapfile/index.html

Note the new "language menu" on the right site. Also, just the mapfile
subdirectory is translated yet. All other directories contain the
English docs.

With this way, its not possible to auto deliver browser requested
languages. Instead the user has to choose his favorite language. But
IMHO this should not be a problem. The English doc will be the preferred
language. Every other language would be optional with no guarantee.

Some further conditions apply:
- all documents need to have the same file name in every language
subdirectory
- if there is no translation for a particular file, there is no warning
message (see [1], I just removed the unix installation file), the text
is just missing
- if there is an directory missing, the corresponding toc entry will not
be a link (see [2], I removed the 'input' directory), also no warning

Maybe it is possible to implement some kind of default error page which
gets shown when an particularly translation is not available (with link
to default English docu).

The latex/pdf generation is also working [3], but I didn't changed the
code yet to copy the file to the right destination.


>>
>> Third question is how to maintain the translations. I volunteer for the
>> German part. But how would I (or others) get notified when the English
>> docs get updated? I would like to keep the translation synchron with the
>> English one.
> 
> This is a hard problem.  We have finally made it easy enough for people
> just go edit the docs as they need to.  If we were to require a ticket
> or something for each edit, it would greatly slow this process down
> again and kill off any (limited) enthusiasm we have for doc writing. 
> About the only reasonable option would be to follow the Trac's RSS feed
> of /trunk/docs/
> 
> http://trac.osgeo.org/mapserver/log/trunk/docs?limit=100&mode=stop_on_copy&format=rss
> 
> 
> but that puts a lot of burden on you to integrate changes into
> translations.
> 

With the above solution the synchronization of translations will not get
easier but also not more difficult. If it would be possible to build an
status page so its easy to visualize the difference in translations,
that would be nice. But I have no clue how to do it... yet :)

I wouldn't mind to follow an rss feed. But then only the translators
would have an overview, the website visitor wouldn't know if or what is
missing.


Lars


[1] http://www.lingner.eu/docs/umn/build/en/html/installation/index.html
[2] http://www.lingner.eu/docs/umn/build/de/html/documentation.html
[3] http://www.lingner.eu/docs/umn/build/de/latex/MapServer.pdf