[mapserver-dev] documentation localization and svn structure

[Howard Butler]

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 :)

> Second question is how to handle untranslated chapters. As for now I
> have everything finished in the mapfile subdirectory and its index  
> page.
> Should I only check in the translated files?

Using the above, I think it would be possible to make an index_de.txt  
at whichever level, and then you could choose to link english/deutch  
docs in as necessary.  I don't know if this is practical or possible  
to keep in sync.

>
> Then I would work through the chapters and do an check in when the  
> next
> one is complete.
>
> 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.

Another thing I think we could do to help is to collate examples and  
other items that aren't going to change from translation to  
translation into files that can be included with ..include:  The  
problem with this is all ..include: files get rebuilt when you issue  
'make', so the more files you have included, the more stuff is  
remade.  A small price that could maybe be fixed with a patch to  
Sphinx though.


>
>
> As I read at this list, the docs get also branched with new releases,
> don't they? So would also the translations then. I cant guarantee to
> finish a new translation with each release... but this depends on the
> volume of changes. As I remember there wasn't huge doc updates with
> every release, so it might be ready at release date.
>
> And finally: There are a few typos in the docs, nothing serious, but
> should I report them or just fix it.

Fix it.