wiki:TranslationGuidelines

Guidelines for Translators

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

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

  1. 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
    
  1. 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."
    
  1. From times to time, enter your working copy and update its content, so you can deal with the latest files versions:
        svn up
    
  1. Goto step 2 and continue...

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