Document Actions

Guidelines for Translators

by Alexander Limi — last modified April 5, 2008 - 14:59

Contributors: Dorneles Treméa, Hanno Schlichting

This document documents the correct approach of translating Plone, you should read all of it before you start translating Plone into your language.

Overview

If you want to translate Plone into your language, we here present you with a brief overview on how to get started, and some guidelines that you should follow when performing a translation.

Introduction

Currently (April 2008) Plone has 59 different translations. There are about 2100 strings needed for a translation of Plone, some of these are sentences or paragraphs, but the major part are one or two words. These strings are scattered around in Plone, for example in page templates. Other items to translate are widget labels, and workflow states. All those strings are collected in master files. Currently the standard Plone distribution contains ten such .pot files. Each language requires its own .po files that corresponds to the strings or message ids declared in the .pot files. The .pot is the blueprint for the .po files.

In the .pot and .po files, the original strings are mapped to ID-based msgids where possible, which might be different from other translation projects you have participated in. The reason is twofold:

A literal msgid (in other words, the original string) can't cope with differences in meaning for the same word when one word is used to represent two different concepts in the source language. For instance, the word "News" could mean two different things in another language - "News" like in "this is new", and "News" like in "the news on TV". A literal msgid would make it impossible to get this right.
If there is a spelling error or a slight modification in the original source text, a correction would invalidate all the translations of this message. This might not sound like such a big deal, but when you start getting a lot of languages and a lot of strings, it adds up really quickly. The current approach is to correct spelling/phrasing errors in the original text while leaving the msgid, and introduce a new msgid (and removing the old) if the change was significant enough to warrant a new translation.

Tools

When creating the .po files, we recommend using a specialized tool like poEdit, but a normal text editor work fine if you prefer that (both vim and emacs are great for this, and have special modes for PO files). poEdit exists for both Linux and Windows, and a Mac OS X port is underway. There is also KBabel for KDE, but in general we recommend using poEdit since that's what most other people are using, so it's easier to get help, and the diffs stay sane that way. (If you don't know what a diff is, don't worry ;)

If you use a plain text editor instead of a dedicated tool, you should make sure you use utf-8 as your charset, even if your country usually uses iso-8859-* or similar. The reason for this is that Plone uses a few characters (like the ellipsis) that don't have representations in other charsets.

Step-by-step guide

Check if somebody is working on your language already. Even if they do, contact them and offer to help with testing. There's no way the Plone team can know what is a high-quality translation in a language they don't know, so your input is very valuable to us. We want good translations, not just a translation. So if you think something sucks, tell us. The authors of this document have experienced enough bad translations to know how bad an impression this gives of the overall product. Give polite feedback to the mailing list or the translation authors directly if something feels wrong with the translation to your language. A translation can always be made better.
Be sure that you have used Plone enough to grasp the general concepts and how they interact. Plone is an advanced system, so be sure you know enough before you start translating key concepts like workflow. Check the language specific terms for your language, or create one if it doesn't exist. This will help you keep consistent translations for your language. If you end up with creating a new list of language-specific terms, please send it to the translation list so we can add it to plone.org.
Download the files to base your translation on. We recommend that you always use the English language files as your starting point, both because they are always the most current ones (other translations will usually lag a bit behind), and because you should try to match the original text. Translating between similar languages may be tempting (like Danish and Norwegian), but will usually result in a lower quality translation. Of course, if the only language you understand is Italian, and you want to provide a Chinese translation, we prefer this translation compared to not getting one at all :)
(That being said, it can be a good idea to take a peek at what terminology similar languages have chosen to use - there are a few abstract concepts in Plone that may be hard to translate well.)
We have recently split up the master translations file into independent files corresponding to the products Plone consists of. So you need to download and translate all of the following files:
Open your editor of choice and load the first of the master files. Save your file as <product>-<language-code>.po e.g. for Plone French translation: plone-fr.po. Have a look at www.i18nguy.com for the correct language code. An example section can look like this:
```
    #. Default: "Upcoming Events"
    #: ./plone_portlets/portlet_events.pt
    msgid "box_events"
    msgstr ""
```
The first line (marked with Default) shows the exact string that you have to translate. Message attributes in the form ${foo} have to be included in the translated string exactly as they are. These are variables that will be filled in the rendering process. Do not touch this.
The next lines (marked with :) list which templates inside Plone use this string. There might be several templates re-using the same string, but it is normally in the same context. Do not touch this.
The next to last line (starting with msgid) holds the unique identifier for the string. Do not touch this. There are some special msgid's, so be sure to read the FAQ's.
Finally, the last line is where your job starts. Enter the text in your language, be careful to keep the same casing (where appropriate, some languages have different rules that should be applied).
Keep translating (but take breaks, this isn't done in one sitting, and should be spread over a few days anyway - it's repetetive (but rewarding) work.
After you have translated all of plone.pot, you should start on the other five files. Don't worry, you have already mastered the biggest part.
Test your files. Get other people from your own country to test. This means having other people check your file and putting your file in a Plone test instance, browsing it in your language.
If you are unsure about the best translation of a message, you can set it to fuzzy, so others can look at these. Setting a message to fuzzy means adding a "#, fuzzy"-line directly above the line starting with msgid.
If you know how SVN works, you can get an account with us (ask for one at the mailing list) and maintain the files in SVN yourself (see next section), if not, no problem, just e-mail your translation to the Plone Translation mailing list and we will update our download area and put it into the Plone distribution in the next release.
Thank you! Remember to keep the translation updated. We will send notifications when there are major updates (new versions of Plone etc. :)

SVN Instructions

As stated above it's not required to know anything about SVN to help with translations, but after some time you'll see it as a very practical way to keep your translations always synced.

Initially, you need to checkout a working copy (it's only necessary at first time):

    svn co --username=username https://svn.plone.org/svn/collective/PloneTranslations/trunk PloneTranslations

Then update your translation files inside de i18n directory, and send the changes back to the SVN server:
```
    svn ci -m "A message telling about what you just did."
```
From times to times, enter your working copy and update its content, so you can deal with the latest files versions:
```
    svn up
```
Goto step 2 and continue...

For additional SVN instructions, including clients suggestions and a mini FAQ, visit the Plone SVN Repository site.

That's it, a lot easy with a bunch of fun... ;-)

Quality Assurance of translations

Few things destroy the initial impression of a product more quickly than bad translation. Therefore, we need to be as quality-minded as possible about this process.

Two or more independent translators should read the translation so we are sure the language is professional, without spelling errors and written in an elegant style. Use the business form of you language, if your language differentiates between informal and business forms.

Be sure that any reference to menus or buttons (like the "Browse" button to upload a file) matches the term used in the localized operating system.
Test all translations in 1024x768 resolution, especially the tab translations - ideally they should all fit in a 1024x768 screen without wrapping.

Guide to Prefixes

We added certain standard prefixes for IDs so you can understand where they are used (semantic differences are easier to spot this way), and easily locate them. Sorted the IDs will be grouped by type automatically.

heading_ - for <h> elements
description_ - Explanatory text directly below
legend_ - Used in <legend> elements
label_ - For field labels, input labels, i.e. <label>, and for <a> elements
help_ - Any text that provides help for form input.
box_ - Content inside portlets.
listingheader_ - For headers in tables (normally of class "listing").
date_ - For date/time-related stuff. E.g. "Yesterday", "Last week".
text_ - Messages that do not fit any other category, normally inside <p>
batch_ - for batch-related things - like "Displaying X to Y of Z total documents"
summary_ - for table summaries
title_ - for titles on all elements
message_ - for text used with portal_status_message

Prefixes are followed by the underscore character and a short description of what the message is about, e.g. "label_name", "text_product_outdated".

Plone CMS: Open Source Content Management

Sections

Personal tools