Localizing SK2
SK2 in your own language
The current page is intended at translators who would like to contribute to the localization effort.
If you just want to know how to download and use a localization file in order to run Wordpress in your language, please visit the ‘SK2 in your language’ section.”
Work in progress:
Page and scripts are being updated to work with the new doc format. Some of what is written below might be outdated. Stay tuned.
Localization Effort
Thanks to everybody, the localization effort seems to be doing very well now. We already have at least a couple languages nearly complete, and many more on their way.
A couple things:
- I have now set-up a download repository for SK2 l10n files. I created a custom script to generate all the .mo files dynamically from each .po page on this site.
Ultimately, I’ll set up a cron job to run that script running automatically, for now you need to have ‘contributor’ access (see below) to this site and go to: Options->WP .mo Mgr.
- All versions of SK starting 2.1 support localization. To test your language, install the latest version of SK2 (overwrite all the files) and drop the appropriate .mo file in the plugins folder (that is: the .mo file should be at the same level as the ’sk2′ folder). Make sure you have the correct language set up in your wp-config.php file.
- Finally, and importantly: if you are an active contributor to the l10n effort, please send me your name, email and blog URL, using the contact form… So I can give you credits in the final release, as well as communicate with everybody when strings are updated between versions…
Do not hesitate to contact me if you have any questions…
Overview
Spam Karma supports localizations (l10n). Otherwise put, this means SK2.1 and up can be changed to another language by the addition of a single Language file.
SK2.1 has been modified to use gettext, an open-source library already used by WordPress itself and many other open-source software out there. This method makes it very easy for translators to work without any knowledge of PHP or technical details. If you want to know more about how gettext works, you can check out WordPress Localization Page and the section specifically dedicated to Localizing WP Plugins, but this is absolutely not required to help out with SK localization. To help out, all you need is pretty much a knowledge of how to edit a text file and operate a Wiki (both at very basic level).
About the amount of work: as you will notice, the full translation sheet is quite big. However, keep in mind that only the first 20% are really useful to most users (and these are some of the shorter strings too). Translating that first chunk is way enough to make SK2 usable for regular users of another languages. The rest (mostly error codes and debug strings) can be done later on. So do not be scared by the length: happily translate away and do whatever you feel like tacking.
Using the Blog for collaborative localization
In order to help different teams of translators share the load (there is quite a lot of text to translate for one person alone), I have put the translation sheet up here on the Wiki. This means anybody can contribute as much (or as little) as they want, and this should greatly help coordination.
To participate, simply register on this Wiki (in the top-right hand side corner: takes 2 seconds and is mandatory to avoid wiki spam) and take a stab at missing parts in your language. If you do not see an existing template for your language, simply copy/paste the generic template and create a new section. Be sure to read the language-specific instructions if there are any, as well as the general editing instructions below (if you have already done .po/.mo translations, you can skip these).
Important Tip: When using the Wiki to edit a l10n file, make sure you save and reload often, in order to avoid collisions (two people working on the same bit of translation simultaneously).
On the workflow
The idea is for the Doc Blog to hold the l10n source files (.po format) for every language. A small script automatically takes them and turns them into .mo files that people can download and use (for now, this script needs to be ran manually, but I will try to have it run by a cron soon).
If you have experience with gettext and can/want to use poedit to edit the l10n sheet, it shouldn’t be a problem, simply copy-paste back and forth to the blog each time you do so (if you are the only translator, then you don’t have to worry about doing so more than once in a while… if there are many translators on your team, you should make sure you keep the versions synchronized often enough)… This system is not absolutely perfect and slightly annoying for people used to edit locally, but for the meantime, it’s much easier on newbies than using full-on versioning (CVS etc.).
When bumping into any translation problem regarding a particular sentence, here is the protocol I suggest (feel free to suggest a better way):
- If the issue is language-related (e.g. disagreement between translators, difficulties etc.), discuss it in the comment section of your language page. I will try to add an option on each page to allow you to leave general remarks and guidelines there for newcomers.
- If the issue is SK2-related (e.g. a term is unclear or you need context), contact me or leave a note on the main template.
Translation Sheets (.po files)
The current l10n files for each language (you need to login and ask me to update your permissions in order to be able to edit them) are listed in the sidebar on the right.
If your language does not appear in the list below and you would like to add it, contact me and I will create the necessary page (until I do so, you can start translating using the .pot template).
How to edit translation sheets
The localization file for each language will show up as a list of strings in English, followed by their translation in the target language (one localization file per language). All lines can be any of three kind:
- lines starting with # are comments, you can do whatever you want to them, add your own etc.
- lines starting with msgid are the original English sentences (do not touch them)
- lines starting with msgstr are where you put your own translation (see details below).
More specifically, they will appear in groups as such:
# this is a comment
msgid “Original sentence in English”
msgstr “Übersetzung dieses Satzes”
The only small variant is for strings that can have a different translation depending on whether the sentence is singular or plural:
msgid "There is %d apple"
msgstr_plural “There are %d apples”
msgstr[0] “Il y a %d pomme”
msgstr[1] “Il y a %d pommes”
In the above example, msgstr[0] contains the singular translated version (for one apple), msgstr[1] contains the plural version (for more than one). If your language requires more specific cases (e.g. some language require a difference between “one”, “two” and “more than two”), add as many msgstr[n] as necessary (always use the same ‘n’ for the same form). Inversely, if your language only uses one form for both singular and plural, remove msgstr[1] and only use msgstr[0].
Often in the sentences to translate, you will encounter these %d and %s signs… It is essential that you do not remove them from the translation: they will be replaced at runtime by either a number (for %d) or a fragment of sentence (for %s). For instance, above, %d will be replaced by the number of apple there is. In some case, %s will appear stuck to another word, this is not a typo, most of the time, this means it will be replaced by a bit of HTML. For example:
msgid "Please go %shere%s"
In this example, you should translate the word “here” and put a %s on each side of its translation. Then inside SK2, the sentence will probably turn into:
"Please go <a href="http://link/to/somewhere“>here</a>”
And same for your translation.
All right, that’s it for the general explanation. For the most part, really, it consist of msgid/msgstr pairs, and putting a straight translation under the original text… So don’t worry if the explanation above sounds a bit complicated.
A few important remarks:
- Never modify the original msgid string in English (the one that appears above your translation). If you spot a mistake or a typo, let me know and I’ll fix it. But modifying it in the localization file without changing the original SK2 source will result in the translation not appearing at all.
- Be careful of respecting spacing. E.g. if a fragment starts with a space, you should probably have a space a the beginning of your translation. The exception is when a sentence ends with a colon (”:”) and that your language typographic rules doesn’t put spacing after colons; in that case you can safely remove the space in your translation.
- Generally, you can use html entities anywhere you need to, but for characters that belong specifically to your language, you can use UTF-8 characters directly…
- Double-quote characters (”) inside a translated string need to be escaped, by prepending them with a backslash: \”
- At the top of the file, you can fill the values to give yourself proper credits etc. For project handled by a team, please discuss among you to figure out the way to include credits for everybody. If necessary, I can create email addresses to forward to a group of translators.