GLEP:10
Title:Internationalization of www.gentoo.org
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

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 a change in CVS structure regarding the documentation so that the individual translation teams can create a localized Gentoo website as proposed by Bug #23199 [4].

Motivation

Lots of people have shown interest in the internationalization 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 an internationalized website. 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

A better implementation is to fully seperate each language from the other. For instance:

[gentoo]/xml/htdocs/en/doc
[gentoo]/xml/htdocs/en/main
[gentoo]/xml/htdocs/en/proj
...
[gentoo]/xml/htdocs/nl/doc
[gentoo]/xml/htdocs/nl/main
[gentoo]/xml/htdocs/nl/proj
...
[gentoo]/xml/htdocs/fr/doc
[gentoo]/xml/htdocs/fr/main
[gentoo]/xml/htdocs/fr/proj
...

This implementation has several advantages:

  • Easy (and more secure) CVS permissions

    Every translation team can now be contained in its own group regarding permissions. That group has access to the full [gentoo]/xml/htdocs/${LANGUAGE} directory and subdirectories. Other languages (including English) cannot be touched by the translation teams.

  • Better integration regarding the website

    Currently, the website's documentation page [5] lists all translations too. Every time a new translation is uploaded, the links are adjusted. With the new structure, the translation teams are in charge of their own documentation page which can be found through http://www.gentoo.org/${LANGUAGE}/main/docs.xml.

  • Internationalization of the website

    In this stadium http://www.gentoo.org/${LANGUAGE} would host the internationalized Gentoo web site. The infrastructure-team would then make sure that http://${LANGUAGE}.gentoo.org refers to the beforementioned URL.

This CVS restructure shouldn't take much time, it does require an atomic move of the existing directories, meaning CVS access for all affected parties (and this includes the Gentoo Project webpages) would be unavailable during the transition. It also requires a rewrite of permissions which is discussed further down this GLEP.

Internationalized Website

The Gentoo web servers (and their update-pace) aren't created for high-volume data transfers or updates. Therefor a consensus was made that the teams in charge of the internationalization of the Gentoo web site (in this proposal the translation teams) would not create a blog-like situation, but link existing localised gentoo communities [1] from the http://${LANGUAGE}.gentoo.org website.

Some people might ask why we wouldn't just have http://${LANGUAGE}.gentoo.org refer (through DNS or otherwise) to the respective community site. This is because that implementation is only plausible if there is only one community site regarding the language/country. However, there can be several such community sites, and providing one with the referral and not the other would be discriminating.

Permissions

The proposed implementation would result in the following possible permission scheme (all read/write):

cvswebdoc:      [gentoo]/xml/htdocs/en/main and [gentoo]/xml/htdocs/en/doc
cvsnlweb:       [gentoo]/xml/htdocs/nl
cvsfrweb:       [gentoo]/xml/htdocs/fr
...
cvskernel:      [gentoo]/xml/htdocs/en/proj/kernel
cvsgdp:         [gentoo]/xml/htdocs/en/proj/gdp
cvsinfrastruct: [gentoo]/xml/htdocs/en/proj/infrastructure

As you can see, the translation teams are in charge of the whole internationalization: translation of website, projects, documentation.

The English documentation team is contained in cvswebdoc and has access to the doc/ subdirectory (in which the documentation resides) and the main/ subdirectory (in which the docs.xml page and others reside).

The project web pages themselves are contained in seperate groups as is currently the case.

Backwards Compatibility

Although nothing gets lost, the new implementation is not compatible with the current one. However, due to the nature of documentation (and website) this is not a problem.

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
[5]http://www.gentoo.org/main/en/docs.xml