/[gentoo]/xml/htdocs/proj/en/glep/glep-0010.txt
Gentoo

Diff of /xml/htdocs/proj/en/glep/glep-0010.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.4
1GLEP: 10 1GLEP: 10
2Title: Internationalization of www.gentoo.org 2Title: Localized Gentoo Sites
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.4 $
4Last-Modified: $Date: 2003/08/04 18:03:54 $ 4Last-Modified: $Date: 2004/08/22 13:57:11 $
5Author: Sven Vermeulen <swift@gentoo.org> 5Author: Tobias Scherbaum <dertobi123@gentoo.org>, Sven Vermeulen <swift@gentoo.org>
6Status: Draft 6Status: deferred
7Type: Standards Track
8Content-Type: text/x-rst
9Created: 4 Aug 2003 7Created: 4-Aug-2003
10Post-History: 4-Aug-2003 8Post-History: 4-Aug-2003, 22-Aug-2003, 14-Mar-2004, 2-May-2004, 22-Aug-2004
11 9
12Abstract
13========
14 10
15The `Gentoo web site`_ is the main source of documentation regarding 11Status
16Gentoo itself. It hosts all documents that the `Gentoo Documentation 12======
17Project`_ delivers, including all made translations.
18 13
19.. _Gentoo web site: http://www.gentoo.org 14Due to insufficient resources, the doc team is unable to implement
20.. _Gentoo Documentation Project: http://www.gentoo.org/proj/en/gdp 15this GLEP at this time. It has therefore been marked "deferred".
21 16
22This GLEP proposes a change in CVS structure regarding the documentation 17Abstract:
23so that the individual translation teams can create a localized Gentoo 18=========
24website as proposed by `Bug #23199`_.
25 19
26.. _Bug #23199: http://bugs.gentoo.org/show_bug.cgi?id=23199 20The Gentoo Website [#gentoo]_ is the main source of documentation regarding
21Gentoo itself. It hosts all documents that the Gentoo Documentation Project
22[#gdp]_ delivers, including all made translations. In addition the website
23contains the GWN and its translations and several news items.
27 24
25
28Motivation 26Motivation:
27===========
28
29Lots of people have shown interest in the localization proposal, and
30even the infrastructure team has given positive feedback. However, due
31to lack of a good roadmap and proposal this suggestion has never grown
32beyond what it is now: a suggestion. Between the first draft of this
33proposal and now some communities grown faster than others. Actually it
34is obvious that we have big communities (lots of users, lots of
35translators) and smaller communities (less users, less translators). If
36we speak about localized Gentoo sites we need to find a capable
37solution for small and even bigger communities. This leads us to a
38point where the lead translator can decide between a small localized
39site including necessarily translated documents and only some
40additional pages and a bigger variant with lots of translated gdp
41documents, translated news and gwn plus additional pages.
42
43
44Rationale:
29========== 45==========
30 46
31Lots of people have shown interest in the internationalization proposal, 47The current layout regarding documentation in the CVS is as follows:
32and even the infrastructure team has given positive feedback. However, 48
33due to lack of a good roadmap and proposal this suggestion has never 49 [gentoo]/xml/htdocs/doc/en/*
34grown beyond what it is now: a suggestion. 50 [gentoo]/xml/htdocs/doc/nl/*
51 [gentoo]/xml/htdocs/doc/fr/*
35 52
36The current CVS structure (and permissions) are insufficient to implement an 53However, there are several other documents (about, policy, etc) in
37internationalized website. The current permissions are to broad while they 54main/$lang:
38should be very strict, the current layout is too fragmented while it should be
39grouped together.
40 55
41Rationale
42=========
43
44The current layout regarding documentation in the CVS is as follows::
45
46 [gentoo]/xml/htdocs/doc/en/*
47 [gentoo]/xml/htdocs/doc/nl/*
48 [gentoo]/xml/htdocs/doc/fr/*
49 ...
50
51However, the documentation index page itself (and several other
52important parts of the Gentoo website) are structed like this::
53
54 [gentoo]/xml/htdocs/main/en/* 56 [gentoo]/xml/htdocs/main/en/*
55 [gentoo]/xml/htdocs/main/nl/* 57 [gentoo]/xml/htdocs/main/nl/*
56 [gentoo]/xml/htdocs/main/fr/* 58 [gentoo]/xml/htdocs/main/fr/*
57 ...
58 59
59This structure makes it very difficult for assigning permissions to the 60This structure makes it very difficult for assigning permissions to the
60individual translation teams, and even more difficult to really localise 61individual translation teams, and even more difficult to really localize
61the Gentoo Website. At this very moment, the translation teams can edit 62the Gentoo Website. At this very moment, the translation teams can edit
62documents of other languages or even the master English documents. English 63documents of other languages or even the master English documents. English
63reviewers and editors can touch documents of languages they possibly don't 64reviewers and editors can touch documents of languages they possibly don't
64even know. Although we do trust every single documentation editor, a better 65even know. Although we do trust every single documentation editor, a better
65implementation is advisable. 66implementation is advisable. We also can't give access to well-known
67but non-dev translators.
66 68
67We want to restructure the current layout so that the Gentoo Website is 69We want to restructure the current layout so that the Gentoo Website is
68more easily internationalized. 70more easily internationalized.
69 71
70Implementation
71==============
72 72
73CVS Structure 73Implementation:
74------------- 74===============
75 75
76A better implementation is to fully seperate each language from the 76Website Pages:
77other. For instance:: 77--------------
78 78
79 [gentoo]/xml/htdocs/en/doc 79The Lead Translator can choose if he wants to maintain a "small" or a
80 [gentoo]/xml/htdocs/en/main 80"big" localized site. All localized sites will be accessible on
81 [gentoo]/xml/htdocs/en/proj 81http://$lang.gentoo.org which will point to [gentoo]xml/htdocs/$lang.
82 ... 82All localized sites must be implemented in GuideXML.
83 [gentoo]/xml/htdocs/nl/doc
84 [gentoo]/xml/htdocs/nl/main
85 [gentoo]/xml/htdocs/nl/proj
86 ...
87 [gentoo]/xml/htdocs/fr/doc
88 [gentoo]/xml/htdocs/fr/main
89 [gentoo]/xml/htdocs/fr/proj
90 ...
91 83
92This implementation has several advantages: 84Requirements for "small" localized sites:
85.........................................
93 86
94* Easy (and more secure) CVS permissions 87 - all documents marked as required in our Translators Howto
88 - $lang/main/translators.xml, listing of all translators (including
89 GWN translators)
90 - $lang/main/communities.xml, listing of all community sites available in $lang
91 - index.xml "welcome page", listing of available ressources on
92 $lang.gentoo.org (i.e. links to documentation, translators.xml and
93 communities.xml)
95 94
96 Every translation team can now be contained in its own group regarding 95Requirements for "big" localized sites:
97 permissions. That group has access to the full 96.......................................
98 [gentoo]/xml/htdocs/${LANGUAGE} directory and subdirectories. Other 97
99 languages (including English) cannot be touched by the translation 98 - all documents marked as required in our Translators Howto
100 teams. 99 - $lang/main/translators.xml, listing of all translators (including
100 GWN translators)
101 - $lang/main/communities.xml, listing of all community sites available in $lang
102 - translated $lang/main documents
103 - translated $lang/news/gwn
104 - translated news items ($lang/news) (only translated news items,
105 news items on a per-lang basis aren't allowed)
101 106
102* Better integration regarding the website
103 107
104 Currently, the website's `documentation page`_ lists all translations 108CVS Structure:
105 too. Every time a new translation is uploaded, the links are adjusted. 109--------------
106 With the new structure, the translation teams are in charge of their
107 own documentation page which can be found through
108 http://www.gentoo.org/${LANGUAGE}/main/docs.xml.
109 110
110* Internationalization of the website 111Actual scheme, everything is relative to [gentoo]/xml/htdocs::
111 112
112 In this stadium http://www.gentoo.org/${LANGUAGE} would host the 113 main/en Contains the main Gentoo Website (about, policy, lists, etc.)
113 internationalized Gentoo web site. The infrastructure-team would then 114 main/$lang Contains some translated Website pages
114 make sure that http://${LANGUAGE}.gentoo.org refers to the 115 doc/en Contains the master English Documentation
115 beforementioned URL. 116 doc/$lang Contains the translated Documentation
117 news Contains English news items
118 news/en/gwn Contains the master English GWNs
119 news/$lang/gwn Contains translated GWNs
120 proj/en Contains the project Webpages
116 121
117.. _documentation page: http://www.gentoo.org/main/en/docs.xml 122Proposed scheme, relative to [gentoo]/xml/htdocs::
118 123
119This CVS restructure shouldn't take much time, it does require an atomic 124 $lang/main Contains some translated Website pages
120move of the existing directories, meaning CVS access for all affected 125 $lang/doc Contains the translated Documentation
121parties (and this *includes* the Gentoo Project webpages) would be 126 $lang/news Contains translated news items
122unavailable during the transition. It also requires a rewrite of permissions 127 $lang/news/gwn Contains translated GWNs
123which is discussed further down this GLEP.
124 128
125 129Mail:
126Internationalized Website 130-----
127-------------------------
128 131
129The Gentoo web servers (and their update-pace) aren't created for 132All mails to www-$lang@gentoo.org should be forwarded to the Lead
130high-volume data transfers or updates. Therefor a consensus was made 133Translator and his Follow-Up.
131that the teams in charge of the internationalization of the Gentoo web
132site (in this proposal the translation teams) would not create a
133blog-like situation, but link existing localised gentoo communities [1]_
134from the http://${LANGUAGE}.gentoo.org website.
135 134
136Some people might ask why we wouldn't just have
137http://${LANGUAGE}.gentoo.org refer (through DNS or otherwise) to the
138respective community site. This is because that implementation is only
139plausible if there is only one community site regarding the
140language/country. However, there can be several such community sites,
141and providing one with the referral and not the other would be
142discriminating.
143 135
144Permissions 136XSL:
145----------- 137----
146 138
147The proposed implementation would result in the following possible 139We need to "hack" our guide.xsl to support something like inserts.xml for the
148permission scheme (all read/write):: 140whole site.
149 141
150 cvswebdoc: [gentoo]/xml/htdocs/en/main and [gentoo]/xml/htdocs/en/doc
151 cvsnlweb: [gentoo]/xml/htdocs/nl
152 cvsfrweb: [gentoo]/xml/htdocs/fr
153 ...
154 cvskernel: [gentoo]/xml/htdocs/en/proj/kernel
155 cvsgdp: [gentoo]/xml/htdocs/en/proj/gdp
156 cvsinfrastruct: [gentoo]/xml/htdocs/en/proj/infrastructure
157 142
158As you can see, the translation teams are in charge of the whole
159internationalization: translation of website, projects, documentation.
160 143
161The English documentation team is contained in cvswebdoc and has access 144.. [#gentoo] http://www.gentoo.org
162to the doc/ subdirectory (in which the documentation resides) and the 145.. [#gdp] http://gdp.gentoo.org
163main/ subdirectory (in which the docs.xml page and others reside).
164 146
165The project web pages themselves are contained in seperate groups as is
166currently the case.
167
168Backwards Compatibility
169=======================
170
171Although nothing gets lost, the new implementation is not compatible with the
172current one. However, due to the nature of documentation (and website) this is
173not a problem.
174
175References
176==========
177
178.. [1] A sum of such community sites can be found at
179 http://dev.gentoo.org/~liquidx/communities.html
180
181Copyright
182=========
183
184This document has been placed in the public domain.

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.4

  ViewVC Help
Powered by ViewVC 1.1.20