Project:Forums/Translator guide

From Gentoo Wiki
Jump to:navigation Jump to:search


Targeted Audience

The aim of this guide is to provide the basic guidelines to anyone working on translations for the forums. This includes those with direct CVS access as well as those who don't. Detailed instructions are provided for both groups.

Reasons for Translations

When new features are released to the Gentoo Forums, either by Gentoo or by phpBB, new phrases and words are added. Typically they are added to the English language pack only, this means that anyone using a different language pack will see these phrases in English. The supported languages are listed below.

  • Chinese (simplified)
  • Chinese (traditional)
  • Danish
  • Dutch
  • Esperanto
  • Finnish
  • French
  • German
  • Greek
  • Italian
  • Norwegian
  • Polish
  • Portuguese
  • Russian
  • Spanish
  • Swedish

Translator Guidelines

File Structure

The files to be translated reside within the gentoo-projects/forums/translations CVS directory, here you will find subdirectories for each supported language. In each language directory there is a README containing instructions as well as the files that need translating. New words or phrases that are introduced when we make modifications will be added to lang_extra.php. When phpBB adds a new phrase we will add it to the bottom of lang_main.php.

There are also two subdirectories to be found in each language directory: an images directory that contains translations of textual images and an email directory which contains email templates which are used when an email is sent to a user, e.g. for topic reply notifications or registration activation.

The first few lines (everything up to the first blank line) are email headers. The header names start at the beginning of the line and end with a colon character ':'. The header names should NOT be translated as this can cause email subjects to be sent in the wrong language.

So for the following email header:

CODE English email header
Subject: Topic Reply Notification - {TOPIC_TITLE}

The following translation should be used:

CODE Translated email header
Subject: <translation> - {TOPIC_TITLE}

The files will usually be php files where it's important to keep the syntactical structure in place. Only the textual strings should be translated. Any other code structures should be kept in place, including code within those strings. Comments (anything after a # or //) can optionally be translated. The line-wrapping used in these files should also be preserved. Also extra whitespace or comments shouldn't be added before <?php or after the last ?> as this causes php to show an error.

So in the following example only the string '%sThis%s is an example' should be translated, ensuring that the %s are kept in place.

CODE Translation example
$lang['Example'] = '%sThis%s is an example'; // this is a comment


If you are a Gentoo Developer/Translator then you can be added to the cvsforumtrans group on so that you have write access to the translations directory. This will give you full access to commit translations. Someone from Gentoo's Infrastructure or Community Relations projects should be able to add you to the cvsforumtrans group. Instructions for getting started with CVS can be found in the Gentoo Linux CVS Tutorial.

Use the following instructions for working with the translations CVS.

CODE CVS instructions
cvs co gentoo-projects/forums/translations
(Edit the relevant files)
cd gentoo-projects/forums/translations/$LANGUAGE
$EDITOR lang_extra.php
(Always make sure you update before committing)
cvs up
cvs ci -m "Added translations for $LANGUAGE" lang_extra.php
Always make sure you use the right character encoding for the files, the encoding is shown in the README.

Working Without CVS Access

If you don't have CVS access you can still help out with the translations. You will need to add your diffs to Gentoo's Bugzilla then someone with CVS access will check them in. You can download the files to be translated using Gentoo's ViewCVS. Make sure you make a note of the revision number of the file downloaded. Once you've made your translations you need to create a diff.

CODE Create a diff
diff -uB original_file.php translated_file.php > file_name.php.diff

Once you've created the diff you need to create a bug report. Make sure you use the Gentoo Infrastructure product and the Forums component. The summary should be in the format "[language] Translation for file_name.php". In the report you should specify which CVS revision number this is a diff against. Once you've created the bug report you should add your diff as an attachment.

Testing & Deployment

Testing Translations

The translations are kept separate from the code that is deployed onto the forums. When you've added a translation you can request that someone with the right access adds the files to our test server. You will be able to find someone to do this in the #gentoo-forums (webchat) IRC channel. You will also be given the username and password needed to access the test server. The test server is used to test new features and bug fixes so sometimes things may not always work correctly.

All translations must be tested before they can be deployed onto the forums.


Once the translations have been tested they will be ready for deployment onto the forums. This will happen during the normal release cycle and they will go live the next time the forums are upgraded, which is usually when we have new features to be released.


This mailing list has been set up to help coordinate the translation efforts. If you have any questions about the translations or the processes used please use this list. To subscribe send an empty email to:

IRC - #gentoo-forums

If you need any help with testing and deployment of the translations you can get hold of a Forums Administrator in the #gentoo-forums (webchat) IRC channel.

Forums Test Server

A test server is available for you to test your translations. This server is password protected, the username/password will be supplied to you when you need it. This server's database is a snapshot of the live Forum and is not always up to date. If you do not have an account on this server please contact a Forums Administrator.