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

  ViewVC Help
Powered by ViewVC 1.1.20