--- xml/htdocs/proj/en/glep/glep-0010.html 2003/08/04 18:27:15 1.1 +++ xml/htdocs/proj/en/glep/glep-0010.html 2003/08/24 22:11:46 1.2 @@ -9,7 +9,7 @@ - GLEP 10 -- Internationalization of www.gentoo.org + GLEP 10 -- Localization for Gentoo Community @@ -31,7 +31,7 @@ GLEP:10 -Title:Internationalization of www.gentoo.org +Title:Localization for Gentoo Community Version:1.1 @@ -47,7 +47,7 @@ Created:4 Aug 2003 -Post-History:4-Aug-2003 +Post-History:4-Aug-2003, 22-Aug-2003 @@ -55,42 +55,41 @@

Contents

-

Abstract

-

The Gentoo web site [2] is the main source of documentation regarding +

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].

+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 internationalization proposal, +

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 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.

+

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

+

Rationale

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

 [gentoo]/xml/htdocs/doc/en/*
@@ -117,134 +116,107 @@
 more easily internationalized.

-

Implementation

+

Implementation

-

CVS Structure

-

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

+

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:

-[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
-...
+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
 
-

This implementation has several advantages:

- -

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

+

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:

-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
+- 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.
 
-

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

- +

References

+
-
[1]A sum of such community sites can be found at +
[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
[2]http://www.gentoo.org
- +
- +
[4]http://bugs.gentoo.org/show_bug.cgi?id=23199
[3]http://www.gentoo.org/proj/en/gdp
- +
- +
[5]http://www.gentoo.org/main/en/docs.xml
[4]http://bugs.gentoo.org/show_bug.cgi?id=23199
@@ -252,7 +224,7 @@