[Geoserver-devel] Talking multilingual documentation framework blues

Michael_Melvin · July 21, 2009, 9:10pm

Okay, I finally have some time to devote to this, and I wanted to restart the conversation.

In order to foster a better international community in our new documentation framework [1], we want to move to have multiple language support in our docs. I created a ticket ( http://jira.codehaus.org/browse/GEOS-3124 ) for this, and to save you a click, will copy the content here:

Current structure:

   svn:
      .../geoserver/VERSION/doc/MANUAL
   http:
      http://docs.geoserver.org/VERSION/MANUAL

I'm proposing to alter this structure to:

   svn:
      .../geoserver/VERSION/doc/LANGUAGE/MANUAL
   http:
      http://docs.geoserver.org/VERSION/LANGUAGE/MANUAL

where

VERSION = [trunk, branches/a.b.c, tags/d.e.f]
LANGUAGE = two letter language code (en = English, it = Italiano, etc.)
MANUAL = [user, developer, docguide]

So as to not break compatibility with existing links, and to provide a default, I propose leaving English as the default when no LANGUAGE is specified in the URL:

docs.geoserver.org/VERSION/MANUAL
= (and maybe one will redirect to the other, not sure)
docs.geoserver.org/VERSION/en/MANUAL

(Apache admins: This is the only part that I may need help with.)

A caveat that may be obvious: Sphinx does not translate anything except for its reserved words as part of its template. So the actual work of making a translation will have to be done manually. A possible problem with this is that the different documentation projects could diverge, but I don't see any way around this.

Does this sound good? Can anyone think of any drawbacks to this system? Who wants to volunteer to create a basic framework for our second language? If I get an a few +1s, I'll set this up this week.

[1] And to avoid interesting language snafus like that found on this page: http://geoserver.org/display/GEOSDOC/1+Getting+Started

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Justin_Deoliveira · July 22, 2009, 2:19am

The scheme sounds good to me, +1. One question, do we have a example of how other projects do this? For instance, how are the python docs organized, they must have translations?

Mike Pumphrey wrote:

Okay, I finally have some time to devote to this, and I wanted to restart the conversation.

In order to foster a better international community in our new documentation framework [1], we want to move to have multiple language support in our docs. I created a ticket ( http://jira.codehaus.org/browse/GEOS-3124 ) for this, and to save you a click, will copy the content here:

Current structure:

   svn:
      .../geoserver/VERSION/doc/MANUAL
   http:
      http://docs.geoserver.org/VERSION/MANUAL

I'm proposing to alter this structure to:

   svn:
      .../geoserver/VERSION/doc/LANGUAGE/MANUAL
   http:
      http://docs.geoserver.org/VERSION/LANGUAGE/MANUAL

where

VERSION = [trunk, branches/a.b.c, tags/d.e.f]
LANGUAGE = two letter language code (en = English, it = Italiano, etc.)
MANUAL = [user, developer, docguide]

So as to not break compatibility with existing links, and to provide a default, I propose leaving English as the default when no LANGUAGE is specified in the URL:

docs.geoserver.org/VERSION/MANUAL
   = (and maybe one will redirect to the other, not sure)
docs.geoserver.org/VERSION/en/MANUAL

(Apache admins: This is the only part that I may need help with.)

A caveat that may be obvious: Sphinx does not translate anything except for its reserved words as part of its template. So the actual work of making a translation will have to be done manually. A possible problem with this is that the different documentation projects could diverge, but I don't see any way around this.

Does this sound good? Can anyone think of any drawbacks to this system? Who wants to volunteer to create a basic framework for our second language? If I get an a few +1s, I'll set this up this week.

[1] And to avoid interesting language snafus like that found on this page: http://geoserver.org/display/GEOSDOC/1+Getting+Started

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Michael_Melvin · July 22, 2009, 4:18pm

Very good question, and you would think Python would have Sphinx translations. However, looking at the official Python docs page:

http://docs.python.org/

Nothing. There appears to be a Wiki with a French translation:

http://wikipython.flibuste.net/PageD'Accueil?action=show&redirect=FrontPage

But it's not in Sphinx and not very well maintained (it's at version 2.4.2). Same thing with some other languages. I looked through a chunk of the page of projects using Sphinx:

http://sphinx.pocoo.org/examples.html

and couldn't hit on an example of what we're trying to do. Sphinx IRC channel has also turned up nothing. I fear we are on our own here.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Justin Deoliveira wrote:

The scheme sounds good to me, +1. One question, do we have a example of how other projects do this? For instance, how are the python docs organized, they must have translations?

Mike Pumphrey wrote:

Okay, I finally have some time to devote to this, and I wanted to restart the conversation.

In order to foster a better international community in our new documentation framework [1], we want to move to have multiple language support in our docs. I created a ticket ( http://jira.codehaus.org/browse/GEOS-3124 ) for this, and to save you a click, will copy the content here:

Current structure:

   svn:
      .../geoserver/VERSION/doc/MANUAL
   http:
      http://docs.geoserver.org/VERSION/MANUAL

I'm proposing to alter this structure to:

   svn:
      .../geoserver/VERSION/doc/LANGUAGE/MANUAL
   http:
      http://docs.geoserver.org/VERSION/LANGUAGE/MANUAL

where

VERSION = [trunk, branches/a.b.c, tags/d.e.f]
LANGUAGE = two letter language code (en = English, it = Italiano, etc.)
MANUAL = [user, developer, docguide]

So as to not break compatibility with existing links, and to provide a default, I propose leaving English as the default when no LANGUAGE is specified in the URL:

docs.geoserver.org/VERSION/MANUAL
   = (and maybe one will redirect to the other, not sure)
docs.geoserver.org/VERSION/en/MANUAL

(Apache admins: This is the only part that I may need help with.)

A caveat that may be obvious: Sphinx does not translate anything except for its reserved words as part of its template. So the actual work of making a translation will have to be done manually. A possible problem with this is that the different documentation projects could diverge, but I don't see any way around this.

Does this sound good? Can anyone think of any drawbacks to this system? Who wants to volunteer to create a basic framework for our second language? If I get an a few +1s, I'll set this up this week.

[1] And to avoid interesting language snafus like that found on this page: http://geoserver.org/display/GEOSDOC/1+Getting+Started

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

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

_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Michael_Melvin · July 24, 2009, 3:24pm

I would love to get another +1 on this. I assume no response means "I'm fine" or "I don't care", but just one more explicit "OK by me" would make me feel better.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Mike Pumphrey wrote:

Very good question, and you would think Python would have Sphinx translations. However, looking at the official Python docs page:

   http://docs.python.org/

Nothing. There appears to be a Wiki with a French translation:

   http://wikipython.flibuste.net/PageD'Accueil?action=show&redirect=FrontPage

But it's not in Sphinx and not very well maintained (it's at version 2.4.2). Same thing with some other languages. I looked through a chunk of the page of projects using Sphinx:

   http://sphinx.pocoo.org/examples.html

and couldn't hit on an example of what we're trying to do. Sphinx IRC channel has also turned up nothing. I fear we are on our own here.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Justin Deoliveira wrote:

The scheme sounds good to me, +1. One question, do we have a example of how other projects do this? For instance, how are the python docs organized, they must have translations?

Mike Pumphrey wrote:

Okay, I finally have some time to devote to this, and I wanted to restart the conversation.

In order to foster a better international community in our new documentation framework [1], we want to move to have multiple language support in our docs. I created a ticket ( http://jira.codehaus.org/browse/GEOS-3124 ) for this, and to save you a click, will copy the content here:

Current structure:

   svn:
      .../geoserver/VERSION/doc/MANUAL
   http:
      http://docs.geoserver.org/VERSION/MANUAL

I'm proposing to alter this structure to:

   svn:
      .../geoserver/VERSION/doc/LANGUAGE/MANUAL
   http:
      http://docs.geoserver.org/VERSION/LANGUAGE/MANUAL

where

VERSION = [trunk, branches/a.b.c, tags/d.e.f]
LANGUAGE = two letter language code (en = English, it = Italiano, etc.)
MANUAL = [user, developer, docguide]

So as to not break compatibility with existing links, and to provide a default, I propose leaving English as the default when no LANGUAGE is specified in the URL:

docs.geoserver.org/VERSION/MANUAL
   = (and maybe one will redirect to the other, not sure)
docs.geoserver.org/VERSION/en/MANUAL

(Apache admins: This is the only part that I may need help with.)

A caveat that may be obvious: Sphinx does not translate anything except for its reserved words as part of its template. So the actual work of making a translation will have to be done manually. A possible problem with this is that the different documentation projects could diverge, but I don't see any way around this.

Does this sound good? Can anyone think of any drawbacks to this system? Who wants to volunteer to create a basic framework for our second language? If I get an a few +1s, I'll set this up this week.

[1] And to avoid interesting language snafus like that found on this page: http://geoserver.org/display/GEOSDOC/1+Getting+Started

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

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

_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Michael_Melvin · July 24, 2009, 9:50pm

This has been done!

* In subversion, I have moved both 1.7.x and trunk docs into a subdirectory called "en". I have created a test user manual project under the "es" directory (parallel) to "en" (in both 1.7.x and trunk) that is ready to be expanded by willing participants. (Should others want to contribute in other languages, suitable directories can be created.)

* URLs to the docs that don't contain a language ("http://docs.geoserver.org/1.7.x/user"\) will redirect to the English version ("http://docs.geoserver.org/1.7.x/en/user"\).
* This isn't done for the online version of the release docs (1.7.4, 1.7.5) since those are static files, although I can move them into a "en" folder if you think it would alleviate confusion.

* Hudson has been updated to build the English docs in their new locations, and this has been tested to work correctly. Once we have content in other languages, we can set up builds for them too.

Whew, I think that's all. Did I forget anything? Anyway, start writing those docs, and let me know if you have questions on how to get started.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Mike Pumphrey wrote:

I would love to get another +1 on this. I assume no response means "I'm fine" or "I don't care", but just one more explicit "OK by me" would make me feel better.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Mike Pumphrey wrote:

Very good question, and you would think Python would have Sphinx translations. However, looking at the official Python docs page:

   http://docs.python.org/

Nothing. There appears to be a Wiki with a French translation:

   http://wikipython.flibuste.net/PageD'Accueil?action=show&redirect=FrontPage

But it's not in Sphinx and not very well maintained (it's at version 2.4.2). Same thing with some other languages. I looked through a chunk of the page of projects using Sphinx:

   http://sphinx.pocoo.org/examples.html

and couldn't hit on an example of what we're trying to do. Sphinx IRC channel has also turned up nothing. I fear we are on our own here.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Justin Deoliveira wrote:

The scheme sounds good to me, +1. One question, do we have a example of how other projects do this? For instance, how are the python docs organized, they must have translations?

Mike Pumphrey wrote:

Okay, I finally have some time to devote to this, and I wanted to restart the conversation.

In order to foster a better international community in our new documentation framework [1], we want to move to have multiple language support in our docs. I created a ticket ( http://jira.codehaus.org/browse/GEOS-3124 ) for this, and to save you a click, will copy the content here:

Current structure:

   svn:
      .../geoserver/VERSION/doc/MANUAL
   http:
      http://docs.geoserver.org/VERSION/MANUAL

I'm proposing to alter this structure to:

   svn:
      .../geoserver/VERSION/doc/LANGUAGE/MANUAL
   http:
      http://docs.geoserver.org/VERSION/LANGUAGE/MANUAL

where

VERSION = [trunk, branches/a.b.c, tags/d.e.f]
LANGUAGE = two letter language code (en = English, it = Italiano, etc.)
MANUAL = [user, developer, docguide]

So as to not break compatibility with existing links, and to provide a default, I propose leaving English as the default when no LANGUAGE is specified in the URL:

docs.geoserver.org/VERSION/MANUAL
   = (and maybe one will redirect to the other, not sure)
docs.geoserver.org/VERSION/en/MANUAL

(Apache admins: This is the only part that I may need help with.)

A caveat that may be obvious: Sphinx does not translate anything except for its reserved words as part of its template. So the actual work of making a translation will have to be done manually. A possible problem with this is that the different documentation projects could diverge, but I don't see any way around this.

Does this sound good? Can anyone think of any drawbacks to this system? Who wants to volunteer to create a basic framework for our second language? If I get an a few +1s, I'll set this up this week.

[1] And to avoid interesting language snafus like that found on this page: http://geoserver.org/display/GEOSDOC/1+Getting+Started

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

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

_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel