Translators Howto for Gentoo Documentation
What does this document explain?
Frequently, people are interested in joining the Gentoo translation teams and
contributing to the translation efforts. However, few of them know what a
translator does, needs to know and how translations are handled. This howto
should answer most questions, and if you still have some questions left,
contact Joshua Saddler or one of the translation team leads.
The Gentoo Documentation Project has a separate
which involves all translation efforts. This subproject is lead by Joshua Saddler and embraces all translation teams.
Every translation team is lead by a Lead Translator. This person is
responsible for all the translations created by the translation team. You can
find the Lead Translator for your language on the Internationalisation Project Page.
In case the Lead Translator is off (vacation, exams, network connectivity
issues, ...) the Translator Follow-Up takes over his job. Both the
Lead Translator and Follow-Up Lead Translator are Gentoo
Developers and should act like one.
Lead Translator and Translator Follow-Up
The Lead Translator acts as the translation lead, his successor is the
Translator Follow-Up. Both developers must be acquainted
with the following important documents:
Although this document is most important for Ebuild-writers, the Lead
Translator and Translator Follow-Up must understand this
document. As Gentoo Developers they are supposed to be able to answer the
common questions about Gentoo that are discussed in this document (such as
QA and masked packages).
Policy: Every Gentoo Documentation Developer, including the Lead
Translator and Translator Follow-Up must read and learn this
policy by heart. It lists all guidelines regarding documentation
development. Not adhering to this policy may lead to sanctions.
Gentoo Linux XML Guide: All Gentoo
Documentation is written in GuideXML, an easy-to-learn and easy-to-write
format that allows us to easily convert the documentation to any format
using XSLT. This document explains how GuideXML is structured and
discloses the Coding Style used in the Gentoo Documentation Project.
The Lead Translator has CVS commit access to the documentation tree in
Gentoo's CVS repository. The Lead Translator and his Follow-Up
are allowed to add and update translations on the website. He is responsible
for the translations on the website and for their accuracy. Failing to
correctly review the translations (resulting in wrong instructions in our
translated guides that don't exist in the English versions) is a serious error.
Every translation team is free to organise their translation efforts as they see
fit. If a team requires a common mailinglist, they can contact Joshua Saddler and/or Gentoo's Infrastructure
Project to setup a translation-specific mailinglist for their language
Unlike the Lead Translator and Translator Follow-Up, the members
of the translation team have no CVS access nor Gentoo Developer status. They do
not have to adhere to the restrictions of the Gentoo Developer as listed above.
It is up to the Lead Translator to provide the translation team members
with the necessary information. However, tips and tricks are available
that can be of help for the translation efforts.
Translators will probably want to subscribe to our CVS mailing list. Whenever a Gentoo
developer commits a new English version of a document, a message is mailed to
this list. The mail contains the list of committed files and a diff of modified
files. Check our mailing lists page to
learn how to subscribe to our lists.
Translation teams can opt to use the metadoc.xml file for their
language. This file also allows translation team members to be listed on the
website when the overview page functionality is used.
Translations available on the Gentoo website must be as accurate as possible.
The installation instructions (Part I of the Gentoo Handbook) are the most important
instructions and have absolute priority over all other documents. They may not
lag more than three days behind on the English document in case of
important updates (which will be announced on firstname.lastname@example.org by the Operational
Manager with "Important" in the subject. Less important updates are not
announced; in this case the documentation must be accurate to two weeks.
Operational documents (listed below) have the second highest priority. Their
translations may not lag more than two weeks behind on the English
document in case of important updates (which will be announced on email@example.com by the Operational
Manager with "Important" in the subject. Less important updates are not
announced; in this case the documentation must be accurate to three
Operational documents are:
All other documentation may not lag more than two months behind.
In case these requirements cannot be met, the translations must be
unlinked from the website until they are updated. In case a complete
language fails to have updated documentation (meaning that most documents are
unlinked from the main page) the Operational Manager is in charge of the
Documentation that does not require translations
The following documents are not required to be translated. They are targeted at
Gentoo Developers who should understand the English language:
However, teams that have enough resources and feel there is a demand amongst
their community for translations of project pages, are welcome to translate
and maintain them. Please do contact the project leads or members to
make sure the documentation is up-to-date and not about to be significantly
changed before undertaking such a translation.
Contacting the Lead Translator
Contributors should contact the Lead Translator listed on the Internationalisation Project Page
to ask how they can help. The Lead Translator should then inform the
potential translation member about how the translations for his language are
In case a contributor believes that the Lead Translator does not perform
well, he can always contact Joshua Saddler to express his concerns.
Requesting Lead Translator / Translator Follow-Up status
All requirements as defined in Lead Translator and
Translator Follow-Up must be met. In addition, the candidate (with
co-operation of his translation team if applicable) must submit a
considerable amount of translated documents to Gentoo's Bugtracking System. This ensures
The language has a certain amount of documents ready for the community
The translation team knows what efforts translations require
The translation team knows how to handle GuideXML and the Coding Style
The documents that are required before a language can be considered for
inclusion on the Gentoo Website are:
Asking for Developer Status
If the preliminary requirements are met, the Lead Translator candidate
and Translator Follow-Up candidate should mail the following
information to Joshua Saddler:
- Full name
- Nickname, registered on irc.freenode.net
- E-mail address
- GPG Information (Key-ID)
Requested Status (Lead Translator or Translator Follow-Up)
Developer Status Progress
If the preliminary requirements are met and all necessary information is
delivered, the candidate will be contacted by a member of the Infrastructure
team for his public SSH Key.
Keep the private key private!
When your account has been set up, a mentor will be assigned (mostly a
senior Lead Translator) to aid you in committing the documents and
managing the translations.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.