GLEP:10
Title:Localization for Gentoo Community
Version:1.1
Last-Modified:2003/08/04 18:03:54
Author:Sven Vermeulen <swift at gentoo.org>
Status:Draft
Type:Standards Track
Content-Type:text/x-rst
Created:4 Aug 2003
Post-History:4-Aug-2003, 22-Aug-2003

Contents

Abstract

The Gentoo web site [2] is the main source of documentation regarding Gentoo itself. It hosts all documents that the Gentoo Documentation Project [3] delivers, including all made translations.

This GLEP proposes some changes regarding the documentation so that we can provide our international users with information regarding Gentoo Communities, as proposed by Bug #23199 [4].

Motivation

Lots of people have shown interest in the localization proposal, and even the infrastructure team has given positive feedback. However, due to lack of a good roadmap and proposal this suggestion has never grown beyond what it is now: a suggestion.

The current CVS structure (and permissions) are insufficient to implement a localized section for each possible country. The current permissions are to broad while they should be very strict, the current layout is too fragmented while it should be grouped together.

Rationale

The current layout regarding documentation in the CVS is as follows:

[gentoo]/xml/htdocs/doc/en/*
[gentoo]/xml/htdocs/doc/nl/*
[gentoo]/xml/htdocs/doc/fr/*
...

However, the documentation index page itself (and several other important parts of the Gentoo website) are structed like this:

[gentoo]/xml/htdocs/main/en/*
[gentoo]/xml/htdocs/main/nl/*
[gentoo]/xml/htdocs/main/fr/*
...

This structure makes it very difficult for assigning permissions to the individual translation teams, and even more difficult to really localise the Gentoo Website. At this very moment, the translation teams can edit documents of other languages or even the master English documents. English reviewers and editors can touch documents of languages they possibly don't even know. Although we do trust every single documentation editor, a better implementation is advisable.

We want to restructure the current layout so that the Gentoo Website is more easily internationalized.

Implementation

CVS Structure

What is needed, is a clear distinction between documentation, newsletters, website and localization. This requires a directory structure in the CVS repository that reflects this distinction.

In the following scheme, everything is relative to [gentoo]/xml/htdocs:

main/en                 Contains the main Gentoo Website
main/${LANGUAGE}        Contains some translated website pages
main/lcl/${COUNTRYCODE} Contains the localized Gentoo page
doc/en                  Contains the master English Documentation
doc/${LANGUAGE}         Contains the translated Documentation
news/en                 Contains the English GWNs
news/${LANGUAGE}        Contains the translated GWNs
proj/en                 Contains the project Webpages

In comparison with what is currently the case, there are no big changes. I've explicitly left out proj/${LANGUAGE} since there is no direct need to translate project websites. If it is desired, then creating a language-specific directory is sufficient.

Website pages

Currently, the main documentation page is main/en/docs.xml. A better implementation would be to have it as doc/en/index.xml. This keeps everything documentation-related together. It also provides us with seperate index pages for each language (doc/${LANGUAGE}/index.xml).

The documentation indexes should mention the other indexes (for other languages), but shouldn't have seperate links for each language per document.

The localization page resides in main/${COUNTRYCODE}/index.xml. This page, which is formatted the same way as the whole Gentoo website, only contains the following information:

- A list of community websites [1]_

- A link to the translated documentation index

- A link to translated Gentoo-webpages::

        * About

        * Social Contract

        * Gentoo Weekly News

If the localization team wants, this can be extended to also provide news-items (such as with the main Gentoo website). In this case, the news items also reside in main/lcl/${COUNTRYCODE}.

Also, http://${COUNTRYCODE}.gentoo.org should point to main/lcl/${COUNTRYCODE}/index.xml.

CVS Permissions

The permissions are now clear and distinct:

- Documentation Developers cannot touch the Gentoo website,
  except for the Index page, which now resides in `doc/en`.

- Translators can only touch files in `doc/${LANGUAGE}` and
  `main/${LANGUAGE}`. 

- The localized pages, which are rather static (since they only
  contain a list of community sites), are maintained by a
  single group for all countrycodes, unless the localization
  pages also contain newsitems, in which case seperate groups
  for each country can exist.

References

[1]A sum of such community sites can be found at http://dev.gentoo.org/~liquidx/communities.html
[2]http://www.gentoo.org
[3]http://www.gentoo.org/proj/en/gdp
[4]http://bugs.gentoo.org/show_bug.cgi?id=23199