A short description of the language handling feature followed by instructions for
translators and co-translators
1. Introduction
As from release 2.0, Ringlink is distributed with a number of language files (PO files). A Ringlink PO
file is a text file, whose filename is a
two character ISO 639 language code, and with the file
extension .po. For instance, the PO file containing the French translation shall
be named fr.po.
At installation, the PO files are placed in the /cgi-bin/ringlink/lang
directory. By running langinstall.pl, language databases are created and saved
in /cgi-bin/ringlink/lang/mo. Then, when running Ringlink, the output texts are
fetched from the applicable databases. At least one database must have been created for
the program to work. The original language used in Ringlink is English and, accordingly,
the English PO file en.po, that is included in the distribution, is a dummy
file. Nevertheless, it's necessary to have the program create a database from
en.po as well, or else English cannot be selected as the default and/or ring
language.
The design of the feature for handling multiple languages in Ringlink is based on
GNU gettext, developed by the free Translation Project. GNU
gettext is used to both create the template file, on which the PO files are
based, and update previously created PO files. In addition to that, the CPAN module
Locale::PGetText has been integrated in Ringlink.
2. How the Ringlink language feature works
The default language for a Ringlink system is set in rlconfig.pm, and the
language for a ring is set in 'Ring admin - Edit ring'. When first calling any of the
admin files (admin.pl, ringadmin.pl, siteadmin.pl,
newring.pl, or newsite.pl), the default language is used to display
text output, but as soon as the program knows which ring you are working with, it
switches to use the ring language. (For rings created with previous versions of Ringlink,
the default language for the system will be used until the ring language has been
explicitly set in 'Ring admin'.)
When navigating a ring, and provided that there is a preferred language set in the
browser which matches one of the installed language databases, the browser preferred
language is used to display text on 'list', 'next5', and 'prev5', and to display possible
Ringlink generated error messages. Otherwise, the ring language is used.
3. Translating to a new language
Besides the PO files, the /cgi-bin/ringlink/lang directory in the
distribution also contains the template file ringlink.pot. When starting a
translation to a new language, you shall simply copy ringlink.pot to
??.po and edit the so created PO file.
But before that, you should check in the table below whether anybody else has started
a translation to the same language already. If not, please send a note to the
Ringlink-open mailing list and let us
know that you are starting a new translation, so we can update the table. If somebody else previously has started a translation to the language you are
interested in, you can become a co-translator. Just send an email message to the
translator. We are interested in being notified about new co-translators too, so the
table also can be updated with this information.
So, what else can be said about the translation to a new language? The
GNU gettext manual is a rather long document, parts of which are
relevant when translating Ringlink, parts of which are not. You are recommended to at
least review that document to get an idea what this whole thing is about.
But as usual there are shortcuts... You can find guidance how to edit the PO file by
studying previously created files. And, of course, if you are not sure about a certain
detail, you can simply test how it appears.
One thing worth mentioning is that some msgid strings include one or more
%s or %d conversions. By default, when there are more than one such
conversion in a string, they are replaced in the final output with arguments in a
pre-defined order. In some translations, there may be a need to change that order.
Assume, for instance, that a msgid string includes two %s conversions.
To switch the order, in which the arguments are passed to the translated string, you can
first write %2$s and then %1$s.
For the time being, translation related questions or concerns should preferrably be
posted to Ringlink-open.
One important moment is to install the new PO file and go through the whole Ringlink
program, in order to ensure that the translated strings appear as intended, and that the
translation makes sense.
When you and possible co-translators are satisfied, please send the file to the
Ringlink project for inclusion in next release by attaching it to a
patch document.
4. Updating a previously created PO file
When the Ringlink development results in new or changed text strings, a new template
file (ringlink.pot) is created. That file is 'merged' with the previously
created PO files into so called POX files, e.g. fr.pox. The POX files, matching
the text strings in the current Ringlink release, are available at
www.ringlink.org/POX/.
The translator doesn't need to bother about all the entries (i.e. pairs of
msgid and msgstr strings) in the POX file, but s/he can concentrate
on the fuzzy and untranslated entries.
Fuzzy entries
Sometimes, when there are new or changed msgid strings, the GNU gettext
tool inserts the translation of a similar msgid as the msgstr string.
An entry including such a program generated 'guess' is called a fuzzy entry, and is
marked with the fuzzy attribute right before msgid, like this:
#, fuzzy
msgid "..."This is done in order to make it easier
for the translator, but there is almost always a need for modifying the msgstr
strings of fuzzy entries.
Important: Once satisfied with the translation, the translator shall
remove the fuzzy attribute.
Untranslated entries
Untranslated entries are easily recognizable by the fact they end with msgstr "".
· 
