source: 3.2/enpraxis.educommons/trunk/enpraxis/educommons/docs/src/LOCALIZATION.txt @ 998

Revision 586, 9.6 KB checked in by tom, 5 years ago (diff)

updated translation instructions

Line 
1====================================
2LinguaPlone Translation Instructions
3====================================
4
5In the context of Department, Course, and ECObjects, translations must occur in a 'top down'
6manner.  A Department must be translated prior to translating a Course, which must be
7translated prior to any objects in the Course being translated.
8
9By default, LinguaPlone will tag newly created content objects in the default language setting
10for the instance. Objects that exist in the ZODB prior to LinguaPlone being installed will be
11'neutral', in terms of their language setting. In order to maintain the correct relationships
12between languages, existing objects must have their language 'set'.
13
14To set an existing object's language, click translate into on the management toolbar, and then
15click manage translations.... This interface will allow you to change the content language
16setting from neutral to the appropriate setting for your instance. 
17
18
19========================================
20Localization with eduCommons $$version$$
21========================================
22
23Overview
24--------
25If you want to translate eduCommons into your language, here are instructions on how to get
26started, as well as some guidelines that you should follow when performing a translation. You do
27not need to know anything about programming to create an eduCommons translation. This
28has been adapted for eduCommons from the `plone translator guidelines
29<http://plone.org/development/teams/i18n/translators-guidelines>`__. Please see our `eduCommons
30Localization Team page <./educommons-localization-team>`__ for a list of our volunteer translators.
31
32Introduction
33------------
34Since eduCommons is customized from Plone, it has built-in support for internationalization. As of
35June 2006 Plone has 56 different translations. eduCommons requires some additional
36translation work, but follows the same process as Plone. Adding an eduCommons translation is much
37less time consuming because most of the translation work has already been done in Plone.
38
39There are about 470 strings needed for a translation of eduCommons (compared to about 1600 strings
40for a Plone translation). Some of these are sentences or paragraphs, but the major part are one or
41two words. These strings are scattered around in Plone, for example in page templates. Other items
42to translate are widget labels, and workflow states. All those strings are collected in master
43files. These are called .pot files. Each language requires its own .po files that
44corresponds to the strings or message ids declared in the .pot files. The .pot is the blueprint for
45the .po files.
46
47
48Tools
49-----
50When 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).
51
52You 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.
53
54
55Step-by-step guide
56------------------
57    1. Check if somebody is working on your language already. Even if they do, contact them and
58    offer to help with testing. There's no way the eduCommons team can know what is a high-quality
59    translation in a language they don't know, so your input is very valuable to us. We want
60    good translations, not just a translation. So if you think something is badly done, tell us.
61    Give polite feedback if something feels wrong with the translation to your language. A
62    translation can always be made better.
63   
64    2. Be sure that you have used eduCommons enough to grasp the general concepts and how they
65    interact. eduCommons is an advanced system, so be sure you know enough before you start
66    translating key concepts like workflow. Check the language specific terms for your language,
67    or create one if it doesn't exist. This will help you keep consistent translations for your
68    language.
69   
70    3. Download the files to base your translation on. We recommend that you always use the
71    English language files as your starting point, both because they are always the most current
72    ones (other translations will usually lag a bit behind), and because you should try to match
73    the original text. Translating between similar languages may be tempting (like Danish and
74    Norwegian), but will usually result in a lower quality translation. Of course, if the only
75    language you understand is Italian, and you want to provide a Chinese translation, we prefer
76    this translation compared to not getting one at all :)
77   
78    4. Each product in eduCommons has .po files located in the locales directory. We have combined
79    all these files in a single location of ease of translation. It can be accessed here:
80    http://educommons.com/localization/localization-files.zip
81    If you wish to translate a language for which we do not currently have translation files,
82    please contact us at info [at] educommons [dot] com.
83   
84   
85    5. Open poEdit or your editor of choice and load the first of the master files. In poEdit
86    select File --> Open (for existing .po translation files) or File --> New catalog from POT file.
87    (to create a new translation from a .pot file). Be sure to set the language and language code in
88    Catalog --> Settings. With poEdit or other editors you will need to save your new translation files
89    as <product>-<language-code>.po (e.g. for a French translation: plone-fr.po, eduCommons-fr.po, etc).
90    Have a look at http://www.i18nguy.com for the correct language code.
91
92    6. In poEdit, the first line shows the exact string that you have to translate. Your translation is
93    entered in the area below the original string. It's easy. This is why we recommend poEdit.
94   
95    7. In other text editors things will look a little different. An example section can look like this:
96
97      |   #. Default: "Export"
98      |   #: ../skins/eduCommons/Export_form.cpt
99      |   msgid "Export"
100      |   msgstr ""
101      |
102     
103      The first line (marked with Default) shows the exact string that you have to translate.
104      Message attributes in the form ${foo} have to be included in the translated string exactly
105      as they are. These are variables that will be filled in the rendering process. Do not touch
106      this.
107   
108      The next lines (marked with :) list which templates inside eduCommons use this string. There
109      might be several templates re-using the same string, but it is normally in the same context.
110      Do not touch this.
111   
112      The next to last line (starting with msgid) holds the unique identifier for the string. Do
113      not touch this.
114   
115      Finally, the last line is where your job starts. Enter the text in your language, be careful
116      to keep the same casing (where appropriate, some languages have different rules that should
117      be applied).
118   
119    8. If there is programming code in a string, only translate the string, not the code. For example in,
120    Default: "${number} items matching your criteria." you would only translate "items matching your
121    criteria." The code in the first part should be left as it is, so the translation will look like this: 
122    ${number} TRANSLATION.
123
124    9. Keep translating (but take breaks, this isn't done in one sitting - it's repetitive (but
125    rewarding) work. After you have translated all of plone.pot, you should start on eduCommons.pot.
126    Don't worry, you have already completed the biggest part.
127   
128    10. If you can, test your files. Get other people from your own country to test. This means having other
129    people check your file and putting your file in an eduCommons test instance, browsing it in
130    your language.
131   
132    11. If you are unsure about the best translation of a message, you can set it to fuzzy, so
133    others can look at these. Setting a message to fuzzy means adding a "#, fuzzy"-line directly
134    above the line starting with msgid (poEdit has a button for this).
135   
136    12. Since some of the translation files are hosted on the Plone Collective, if you know how SVN
137    works, you can get an account with Plone (Here's how to request write access to the Collective.)
138    and maintain the files in SVN yourself (see next section). If not, no problem, just e-mail your
139    translation to us at info [at] educommons [dot] com, and we will add it for you and put it into the
140    eduCommons distribution in the next release. We will also add you to our our `eduCommons
141    Localization Team page, here: http://educommons.com/documentation/how-to/educommons-localization-team
142   
143    13. Please check on your translations periodically to keep them updated as new versions are
144    released. A quick search for "" will reveal any new or missing stings that need to be translated.
145   
146    14. If you have other questions or about contributing a translation to eduCommons please contact
147    us at info [at] educommons [dot] com. Thank you for you help!
148
Note: See TracBrowser for help on using the repository browser.