Translations are important for some people, while others are doing just fine with the default language, English. Even if you fall into the latter group of people, a translation in your language may help others a lot.
Compared to some other software packages, Net Responsibility (NR) has pretty small translation files that shouldn't take very long to translate. The important thing to remember is that good translation files should stay updated to avoid any discrepancy compared to the default language. For this reason we need translators to commit themselves to update the files before each release of the software. More details on this later on.
Note: Versions prior to 3.1 do not have multilingual support. It's perfectly possible to create translations without having 3.1 or later installed, but not to try them out live.
The translations, like the rest of the source code, are in the NR code repository (repo), which is handled by the distributed version control system (DVCS) Mecurial and hosted at BitBucket. More info about how to work with Mercurial and BitBucket is found in the "Repository Management" guide. There it is also described how to submit changes. The same technique applies to the translations.
NR is designed to make use of different plugins, so each plugin has its own locale (translation) file. The files to look for are found in these paths, relative to the source code root directory:
locale/en_EN.xml plugins/*/locale/en_EN.xml
The asterisk represents any folder found in the plugins directory.
Let's first go through the basics of XML. Assume we have a file that looks like this:
<root> <name>Robert</name> <messages> <welcome>Hello ${name}! Nice to meet you.</welcome> <goodbye>Goodbye ${name}</goodbye> </messages> <!-- This is only a comment --> </root>
Every element has the structure <tag>Content</tag>, where tag can be anything. Notice how it's opened by <tag> and closed with </tag>. The only difference is the slash. So everything is wrapped up inside elements, and each element may contain other elements. It's also important that all elements are wrapped up inside a root element.
Also note the occurence of ${name}. Let's call it a variable replacement. It will be replaced by the content of the name element. In this example it means that the welcome message will be:
Hello Robert! Nice to meet you.
${name} may be replaced by any element, even nested ones. Reference to the goodbye message looks like ${messages.goodbye}. You may understand it as "the goodbye element inside the messages element". The root element is omitted in variable replacements, otherwise all parents must be specified. This means that the goodbye message may not be specified as ${goodbye} or ${root.messages.goodbye}.
The variable replacements may refer to any element in any locale file, or even the configuration file. You will find that the variable replacements are pretty useful and common in the locale files. When editing a message, keep the variable replacements intact, try to understand what value will be inserted, and create a meaningful message out of it.
The last element to look at is the comment. Comments always begin with <!— and end with —>. Anything in between is ignored by NR. These messages are there to help you understand the structure, but you don't need to translate them unless you want to.
As a translator, you should never change the XML structure, but it's useful to have a basic understanding of it.
So open locale/en_EN.xml in your favorite text editor. It is recommended to use one with syntax highlighting, since it will make it easier to determine the structure.
The first lines you'll notice look like this, more or less:
<?xml version="1.0" encoding="UTF-8"?> <locale language="en_EN"> <translator> <name>Robert Rosman</name> <email>robertrosman@gmx.com</email> <nrVersion>3.1</nrVersion> </translator>
Never mind the very first line. Use your text editor to set the document's encoding to UTF-8, and you're all good.
The next line is the root element. The only thing to edit is en_EN. Change it to the locale code you're translating to. If you're uncertain what this code is, you can start by running these commands in a terminal:
echo $LANG locale -a
The first command prints the locale used by your system, the other shows all installed locales on your computer. On my system the first command prints "sv_SE.UTF-8". Note that only sv_SE should be used here. If none of the locales printed by the commands are correct, either google it or ask us for advice.
Note that the same code should be used when saving the file. The filename should follow the pattern xx_ZZ.xml, where xx_ZZ is your locale code.
Next comes the <translator> tag. Here's some information about who you are. This is very useful when we're about to make a new release and need to update the translations. At that time we need to be able to contact you.
The <nrVersion> element specifies which version of Net Responsibility this translation applies to. Again, this is useful to understand if the locale is outdated.
If you only add to or edit a translation that has an existing translator tag, please copy it and add a new one at the top. The result would be similar to this:
<translator> <name>Your name</name> <email>yourname@example.com</email> <nrVersion>3.2</nrVersion> </translator> <translator> <name>Robert Rosman</name> <email>robertrosman@gmx.com</email> <nrVersion>3.1</nrVersion> </translator>
Now you're about to edit the actual NR messages. Your task is to replace all the readable content between the opening and closing tags with translated messages. Please keep the variable replacements intact.
At a certain point you will reach a comment that looks like this:
<!-- Do not edit the following entries, unless you really know what you're doing! -->
Follow the advice and don't edit any entries below that comment.
When you think you're done, please read through it once again to avoid typos or bad grammar.
The very last step would be to submit your new or edited translation to us, so that we can include it in the next release. This is done as described in the "Repository Management" guide.
Good luck with the translations, and thanks for your efforts!