Gentoo Logo

Translators Howto for Gentoo Documentation


1.  Introduction

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.

2.  Situation


The Gentoo Documentation Project has a separate Internationalisation Project 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:

  • Gentoo Ebuild Policy: 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).
  • Gentoo Documentation 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.

Translation Teams

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 (gentoo-doc-${LANG}

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.

3.  Requirements

Translation Accuracy

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

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

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.

4.  Contributing

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

In case a contributor believes that the Lead Translator does not perform well, he can always contact Joshua Saddler to express his concerns.

5.  Requesting Lead Translator / Translator Follow-Up status

Preliminary Requirements

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 that:

  • 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
  • E-mail address
  • GPG Information (Key-ID)
  • Language
  • 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.


Page updated December 28, 2012

Summary: A frequently asked question is how to become a translator and what actions should be performed both to become one and to act as one. This document tries to explain all this.

Sven Vermeulen

Joshua Saddler

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.