Chapter 3. Documentation

Table of Contents

Building the documentation locally
Editing the User Documentation
Packages to be translated
Mainly built for and used by Xubuntu
Translation guidelines for Xubuntu packages

Building the documentation locally

  • Get the Bzr branch lp:xubuntu-docs.

  • Get the build dependencies for xubuntu-docs.

Editing the User Documentation

Changes to the user documentation should be made to the .xml files under user-docs/C/. Once edited and saved, push changes to your local branch as detailed in Appendix B, Common Reference

Changes to the contributor documentation should be made to the .xml files under contributor-docs/C/. Once edited and saved, push changes to your local branch as detailed in Appendix B, Common Reference

Packages to be translated

These are packages that the Xubuntu team considers important, and should take precedence when translating.

The packages that only exist in Xubuntu

These packages only exist in Xubuntu, so their translation is solely dealt with by Xubuntu translators. These are of high importance for the Xubuntu team.

Used by and essential for Xubuntu

These packages are used by Xubuntu and provide essential features to the Xubuntu experience. When these are translated, the base system is immediately more usable for more people.

Mainly built for and used by Xubuntu

These packages exist outside Xubuntu, but they are mainly built to fit a need in Xubuntu. Unless/until they are spread much wider than now (and have gathered the interest of other translation groups), the Xubuntu translators should take care of translating these packages.

Translation guidelines for Xubuntu packages

These guidelines apply mostly to the Xubuntu documentation. They can generally be applied to any translation with minor modification. If unsure, ask the Documentation team members for assistance.

The language-specific translation groups usually want to encourage some conventions; please contact the appropriate language-specific group before translating.

More general translation guidelines can be found at the Launchpad translations guide.

Maintain translation validity

Tags should not be translated. Where you see a tag in the source string (for example: "<xref linkend="&xubuntu-web;" />"), the tag and anything inside the tag itself should not be translated. It is very important to copy and paste these tags exactly as they appear in the source string. Note: The exception to this is where a tag contains a URL that has an equivalent, translated version. In those cases the translator should use discretion about whether to localise the URL.

Entities should not be translated. Where you see a phrase expressed like "&gt;" or "&xubuntu-web;", do not change this.

Always maintain the order of tags. When you see different tags nested inside each other (for example: "<menuchoice><guimenu>System</guimenu><guimenuitem>Administration</guimenuitem><guimenuitem>Users and Groups</guimenuitem></menuchoice>"), you must always preserve that order carefully - copying and pasting from the source language (English) is the best way to ensure that you do this correctly.


Different programming languages and software might have different variable syntaxes; make sure you are familiar with the appropriate software variable syntax when translating. More information on this can often be found in the translation string comment.

Follow good and existing conventions

Use application and label names found in the (graphical) UI. When translating UI labels and application names, use the term or name that is used on the graphical UI. This makes it easier for the user to follow the instructions. Running the system in both the translation target language and English can help with this.

Do not change the amount of spacing. When translating, do not change the amount of spacing inside our outside tags. Keeping the spacing as it is makes the technical reviewing of the translation easier.

Do not change the type of quotes used inside the tags. The double quotes ( " ) doesn't have the same significance in a DocBook, XHTML or XML tag as the guillemets ( « » ). Using different kind of quotes can potentially develop into validity problems as well.

Never change a tag to another. If you think a tag in the source is invalid or not semantic, file a bug against the package itself instead of changing it in the translation.