--- xml/htdocs/proj/en/glep/glep-0010.html 2003/08/24 22:11:46 1.2 +++ xml/htdocs/proj/en/glep/glep-0010.html 2004/05/02 21:15:23 1.3 @@ -9,7 +9,7 @@ - GLEP 10 -- Localization for Gentoo Community + GLEP 10 -- Localized Gentoo Sites @@ -31,23 +31,19 @@ GLEP:10 -Title:Localization for Gentoo Community +Title:Localized Gentoo Sites -Version:1.1 +Version:$Revision: 1.3 $ -Last-Modified:2003/08/04 18:03:54 +Last-Modified:$Date: 2004/05/02 21:15:23 $ -Author:Sven Vermeulen <swift at gentoo.org> +Author:Tobias Scherbaum <dertobi123 at gentoo.org>, Sven Vermeulen <swift at gentoo.org> Status:Draft -Type:Standards Track +Created:4-Aug-2003 -Content-Type:text/x-rst - -Created:4 Aug 2003 - -Post-History:4-Aug-2003, 22-Aug-2003 +Post-History:4-Aug-2003, 22-Aug-2003, 14-Mar-2004, 2-May-2004 @@ -55,176 +51,157 @@

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

+

Abstract:

+

The Gentoo Website [1] is the main source of documentation regarding +Gentoo itself. It hosts all documents that the Gentoo Documentation Project +[2] delivers, including all made translations. In addition the website +contains the GWN and its translations and several news items.

-

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.

+

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. Between the first draft of this +proposal and now some communities grown faster than others. Actually it +is obvious that we have big communities (lots of users, lots of +translators) and smaller communities (less users, less translators). If +we speak about localized Gentoo sites we need to find a capable +solution for small and even bigger communities. This leads us to a +point where the lead translator can decide between a small localized +site including necessarily translated documents and only some +additional pages and a bigger variant with lots of translated gdp +documents, translated news and gwn plus additional pages.

-

Rationale

+

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/doc/fr/*
+

However, there are several other documents (about, policy, etc) in +main/$lang:

+
[gentoo]/xml/htdocs/main/en/* [gentoo]/xml/htdocs/main/nl/* -[gentoo]/xml/htdocs/main/fr/* -... -
+[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 +individual translation teams, and even more difficult to really localize 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.

+even know. Although we do trust every single documentation editor, a better +implementation is advisable. We also can't give access to well-known +but non-dev translators.

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.

-
+

Implementation:

-

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:

+

Website Pages:

+

The Lead Translator can choose if he wants to maintain a "small" or a +"big" localized site. All localized sites will be accessible on +http://$lang.gentoo.org which will point to [gentoo]xml/htdocs/$lang. +All localized sites must be implemented in GuideXML.

+
+

Requirements for "small" localized sites:

+
+
    +
  • all documents marked as required in our Translators Howto
  • +
  • $lang/main/translators.xml, listing of all translators (including +GWN translators)
  • +
  • $lang/main/communities.xml, listing of all community sites available in $lang
  • +
  • index.xml "welcome page", listing of available ressources on +$lang.gentoo.org (i.e. links to documentation, translators.xml and +communities.xml)
  • +
+
+
+
+

Requirements for "big" localized sites:

+
+
    +
  • all documents marked as required in our Translators Howto
  • +
  • $lang/main/translators.xml, listing of all translators (including +GWN translators)
  • +
  • $lang/main/communities.xml, listing of all community sites available in $lang
  • +
  • translated $lang/main documents
  • +
  • translated $lang/news/gwn
  • +
  • translated news items ($lang/news) (only translated news items, +news items on a per-lang basis aren't allowed)
  • +
+
+
+
+
+

CVS Structure:

+

Actual scheme, everything is relative to [gentoo]/xml/htdocs:

-- 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
+main/en         Contains the main Gentoo Website (about, policy, lists, etc.)
+main/$lang      Contains some translated Website pages
+doc/en          Contains the master English Documentation
+doc/$lang       Contains the translated Documentation
+news            Contains English news items
+news/en/gwn     Contains the master English GWNs
+news/$lang/gwn  Contains translated GWNs
+proj/en         Contains the project Webpages
 
-

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:

+

Proposed scheme, relative to [gentoo]/xml/htdocs:

-- 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.
+$lang/main      Contains some translated Website pages
+$lang/doc       Contains the translated Documentation
+$lang/news      Contains translated news items
+$lang/news/gwn  Contains translated GWNs
 
-
-
-

References

- - - - - -
[1]A sum of such community sites can be found at -http://dev.gentoo.org/~liquidx/communities.html
- - - - - -
[2]http://www.gentoo.org
- +
+

Mail:

+

All mails to www-$lang@gentoo.org should be forwarded to the Lead +Translator and his Follow-Up.

+
+
+

XSL:

+

We need to "hack" our guide.xsl to support something like inserts.xml for the +whole site.

+
- +
[3]http://www.gentoo.org/proj/en/gdp
[1]http://www.gentoo.org
- +
- +
[4]http://bugs.gentoo.org/show_bug.cgi?id=23199
[2]http://gdp.gentoo.org
-