Overview

If you want to translate eduCommons into your language, here are instructions on how to get started, as well as some guidelines that you should follow when performing a translation. You do not need to know anything about programming to create an eduCommons translation. This has been adapted for eduCommons from the plone translator guidelines. Please see our eduCommons Localization Team page for a list of our volunteer translators.

Introduction

Since eduCommons is customized from Plone, it has built-in support for internationalization. As of June 2006 Plone has 56 different translations. eduCommons requires some additional translation work, but follows the same process as Plone. Adding an eduCommons translation is much less time consuming because most of the translation work has already been done in Plone.

There are about 470 strings needed for a translation of eduCommons (compared to about 1600 strings for a Plone translation). 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. These are called .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.

Tools

When creating the .po files, we strongly recommend using a specialized tool called poEdit (http://www.poedit.net). This makes the translation process very easy. poEdit exists for both Linux and Windows, and Mac OS X. When you open a .po file with PoEdit, you will see a list of translations in English and four boxes below. As you click on a line to highlight it, you will see that the top two boxes are for English and Default translations. Type your translation in the lower left box. Do not change the naming of the individual translation files. Just send them back when you are done (you may zip them up if you like).

You can also use a normal text editor if you prefer (both vim and emacs are great for this, and have special modes for PO files). 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. Please review the step-by-step instructions below for more information about the actual translation process.

Step-by-step guide

1. 1. 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 eduCommons 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 is badly done, tell us. Give polite feedback if something feels wrong with the translation to your language. A translation can always be made better.
   2. Be sure that you have used eduCommons enough to grasp the general concepts and how they interact. eduCommons 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.
   3. 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 🙂
   4. Each product in eduCommons has .po files located in the locales directory. We have combined all these files in a single location of ease of translation. It can be accessed here: http://educommons.com/localization/localization-files.zip If you wish to translate a language for which we do not currently have translation files, please contact us at info [at] educommons [dot] com.
   5. Open poEdit or your editor of choice and load the first of the master files. In poEdit select File –> Open (for existing .po translation files) or File –> New catalog from POT file. (to create a new translation from a .pot file). Be sure to set the language and language code in Catalog –> Settings. With poEdit or other editors you will need to save your new translation files as <product>-<language-code>.po (e.g. for a French translation: plone-fr.po, eduCommons-fr.po, etc). Have a look at http://www.i18nguy.com for the correct language code.
   6. In poEdit, the first line shows the exact string that you have to translate. Your translation is entered in the area below the original string. It’s easy. This is why we recommend poEdit.
   7. In other text editors things will look a little different. An example section can look like this:

#. Default: "Export"  
#: ../skins/eduCommons/Export_form.cpt  
msgid "Export"  
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 eduCommons 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.

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

 

1. If there is programming code in a string, only translate the string, not the code. For example in, Default: “${number} items matching your criteria.” you would only translate “items matching your criteria.” The code in the first part should be left as it is, so the translation will look like this: ${number} TRANSLATION. 
2. Keep translating (but take breaks, this isn’t done in one sitting – it’s repetitive (but rewarding) work. After you have translated all of plone.pot, you should start on eduCommons.pot. Don’t worry, you have already completed the biggest part. 
3. If you can, 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 an eduCommons test instance, browsing it in your language. 
4. 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 (poEdit has a button for this). 
5. Since some of the translation files are hosted on the Plone Collective, if you know how SVN works, you can get an account with Plone (Here’s how to request write access to the Collective.) and maintain the files in SVN yourself (see next section). If not, no problem, just e-mail your translation to us at info [at] educommons [dot] com, and we will add it for you and put it into the eduCommons distribution in the next release. We will also add you to our our `eduCommons Localization Team page, here: http://educommons.com/documentation/how-to/educommons-localization-team 
6. Please check on your translations periodically to keep them updated as new versions are released. A quick search for “” will reveal any new or missing stings that need to be translated. 
7. If you have other questions or about contributing a translation to eduCommons please contact us at info [at] educommons [dot] com. Thank you for you help!