/[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.2
1GLEP: 10 1GLEP: 10
2Title: Internationalization of www.gentoo.org 2Title: Localization for Gentoo Community
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.2 $
4Last-Modified: $Date: 2003/08/04 18:03:54 $ 4Last-Modified: $Date: 2003/08/24 22:11:46 $
5Author: Sven Vermeulen <swift@gentoo.org> 5Author: Sven Vermeulen <swift@gentoo.org>
6Status: Draft 6Status: Draft
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Created: 4 Aug 2003 9Created: 4 Aug 2003
10Post-History: 4-Aug-2003 10Post-History: 4-Aug-2003, 22-Aug-2003
11 11
12Abstract 12Abstract
13======== 13========
14 14
15The `Gentoo web site`_ is the main source of documentation regarding 15The `Gentoo web site`_ is the main source of documentation regarding
… …
17Project`_ delivers, including all made translations. 17Project`_ delivers, including all made translations.
18 18
19.. _Gentoo web site: http://www.gentoo.org 19.. _Gentoo web site: http://www.gentoo.org
20.. _Gentoo Documentation Project: http://www.gentoo.org/proj/en/gdp 20.. _Gentoo Documentation Project: http://www.gentoo.org/proj/en/gdp
21 21
22This GLEP proposes a change in CVS structure regarding the documentation 22This GLEP proposes some changes regarding the documentation
23so that the individual translation teams can create a localized Gentoo 23so that we can provide our international users with information regarding
24website as proposed by `Bug #23199`_. 24Gentoo Communities, as proposed by `Bug #23199`_.
25 25
26.. _Bug #23199: http://bugs.gentoo.org/show_bug.cgi?id=23199 26.. _Bug #23199: http://bugs.gentoo.org/show_bug.cgi?id=23199
27 27
28Motivation 28Motivation
29========== 29==========
30 30
31Lots of people have shown interest in the internationalization proposal, 31Lots of people have shown interest in the localization proposal,
32and even the infrastructure team has given positive feedback. However, 32and even the infrastructure team has given positive feedback. However,
33due to lack of a good roadmap and proposal this suggestion has never 33due to lack of a good roadmap and proposal this suggestion has never
34grown beyond what it is now: a suggestion. 34grown beyond what it is now: a suggestion.
35 35
36The current CVS structure (and permissions) are insufficient to implement an 36The current CVS structure (and permissions) are insufficient to implement a
37internationalized website. The current permissions are to broad while they 37localized section for each possible country. The current permissions are to
38should be very strict, the current layout is too fragmented while it should be 38broad while they should be very strict, the current layout is too fragmented
39grouped together. 39while it should be grouped together.
40 40
41Rationale 41Rationale
42========= 42=========
43 43
44The current layout regarding documentation in the CVS is as follows:: 44The current layout regarding documentation in the CVS is as follows::
… …
71============== 71==============
72 72
73CVS Structure 73CVS Structure
74------------- 74-------------
75 75
76A better implementation is to fully seperate each language from the 76What is needed, is a clear distinction between documentation, newsletters,
77other. For instance:: 77website and localization. This requires a directory structure in the CVS
78repository that reflects this distinction.
78 79
79 [gentoo]/xml/htdocs/en/doc 80In the following scheme, everything is relative to [gentoo]/xml/htdocs::
80 [gentoo]/xml/htdocs/en/main
81 [gentoo]/xml/htdocs/en/proj
82 ...
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 81
92This implementation has several advantages: 82 main/en Contains the main Gentoo Website
83 main/${LANGUAGE} Contains some translated website pages
84 main/lcl/${COUNTRYCODE} Contains the localized Gentoo page
85 doc/en Contains the master English Documentation
86 doc/${LANGUAGE} Contains the translated Documentation
87 news/en Contains the English GWNs
88 news/${LANGUAGE} Contains the translated GWNs
89 proj/en Contains the project Webpages
93 90
94* Easy (and more secure) CVS permissions 91In comparison with what is currently the case, there are no big changes.
92I've explicitly left out `proj/${LANGUAGE}` since there is no direct
93need to translate project websites. If it is desired, then creating a
94language-specific directory is sufficient.
95 95
96 Every translation team can now be contained in its own group regarding 96Website pages
97 permissions. That group has access to the full 97-------------
98 [gentoo]/xml/htdocs/${LANGUAGE} directory and subdirectories. Other
99 languages (including English) cannot be touched by the translation
100 teams.
101 98
102* Better integration regarding the website 99Currently, the main documentation page is `main/en/docs.xml`. A better
100implementation would be to have it as `doc/en/index.xml`. This keeps
101everything documentation-related together. It also provides us with
102seperate index pages for each language (`doc/${LANGUAGE}/index.xml`).
103 103
104 Currently, the website's `documentation page`_ lists all translations 104The documentation indexes should mention the other indexes (for other
105 too. Every time a new translation is uploaded, the links are adjusted. 105languages), but shouldn't have seperate links for each language per
106 With the new structure, the translation teams are in charge of their 106document.
107 own documentation page which can be found through
108 http://www.gentoo.org/${LANGUAGE}/main/docs.xml.
109 107
110* Internationalization of the website 108The localization page resides in `main/${COUNTRYCODE}/index.xml`. This
109page, which is formatted the same way as the whole Gentoo website,
110**only** contains the following information::
111 111
112 In this stadium http://www.gentoo.org/${LANGUAGE} would host the 112 - A list of community websites [1]_
113 internationalized Gentoo web site. The infrastructure-team would then
114 make sure that http://${LANGUAGE}.gentoo.org refers to the
115 beforementioned URL.
116 113
117.. _documentation page: http://www.gentoo.org/main/en/docs.xml 114 - A link to the translated documentation index
118 115
119This CVS restructure shouldn't take much time, it does require an atomic 116 - A link to translated Gentoo-webpages::
120move of the existing directories, meaning CVS access for all affected
121parties (and this *includes* the Gentoo Project webpages) would be
122unavailable during the transition. It also requires a rewrite of permissions
123which is discussed further down this GLEP.
124 117
125 118 * About
126Internationalized Website
127-------------------------
128 119
129The Gentoo web servers (and their update-pace) aren't created for 120 * Social Contract
130high-volume data transfers or updates. Therefor a consensus was made
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 121
136Some people might ask why we wouldn't just have 122 * Gentoo Weekly News
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 123
144Permissions 124If the localization team wants, this can be extended to also provide
145----------- 125news-items (such as with the main Gentoo website). In this case, the
126news items also reside in `main/lcl/${COUNTRYCODE}`.
146 127
147The proposed implementation would result in the following possible 128Also, `http://${COUNTRYCODE}.gentoo.org` should point to
148permission scheme (all read/write):: 129`main/lcl/${COUNTRYCODE}/index.xml`.
149 130
150 cvswebdoc: [gentoo]/xml/htdocs/en/main and [gentoo]/xml/htdocs/en/doc 131CVS Permissions
151 cvsnlweb: [gentoo]/xml/htdocs/nl 132---------------
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 133
158As you can see, the translation teams are in charge of the whole 134The permissions are now clear and distinct::
159internationalization: translation of website, projects, documentation.
160 135
161The English documentation team is contained in cvswebdoc and has access 136 - Documentation Developers cannot touch the Gentoo website,
162to the doc/ subdirectory (in which the documentation resides) and the 137 except for the Index page, which now resides in `doc/en`.
163main/ subdirectory (in which the docs.xml page and others reside).
164 138
165The project web pages themselves are contained in seperate groups as is 139 - Translators can only touch files in `doc/${LANGUAGE}` and
166currently the case. 140 `main/${LANGUAGE}`.
167 141
168Backwards Compatibility 142 - The localized pages, which are rather static (since they only
169======================= 143 contain a list of community sites), are maintained by a
144 single group for all countrycodes, unless the localization
145 pages also contain newsitems, in which case seperate groups
146 for each country can exist.
170 147
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 148
175References 149References
176========== 150==========
177 151
178.. [1] A sum of such community sites can be found at 152.. [1] A sum of such community sites can be found at
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2
  ViewVC Help
Powered by ViewVC 1.1.13