Coppermine Photo Gallery 1.3.x - Translator's Guide
One of the major advantages of Coppermine is the fact that all page content can be displayed in different languages, with translations being only in one file (inside the lang directory within coppermine). If you like Coppermine and you want to give something back to the community, why don't you start a translation of coppermine into your language?
There are, however, some rules and guidelines for translation outlined in this document...
Translations for which languages are needed?
There are already several languages supported by coppermine; as the number of language-files for coppermine grows, there may be translations available that were not included into the package you downloaded. Before you actually start to work on a translation, look here:
Who can translate?
In theory, everybody can, but for the first "phase" of translations when a new version of coppermine comes out, the dev team will contact the translators of pervious versions and ask them to translate the new version as well. Those "original" translators are asked to give a feedback first if they're willing to do the translation (before they actually start to work on the translation); the languages of those who say they're not going to do the "new" translation or from those who don't reply at all will be put on a list on [Help wanted]: Translations for CPG1.3.x; anyone who is ready to do the translation for those "orphaned" languages should reply to the thread and assign the translation to himself.
If you can speak a language that hasn't been translated yet and that nobody has assigned himself, please assign it to you.
Coppermine adds a charset meta tag to the header of each ouput file to instruct the browser how to render special chars. You should add the name of the charset you're using for your translation at the very start of the language file, e.g.
$lang_charset = 'iso-8859-1';. You can find a list of charsets at http://www.w3.org/International/O-charset-lang.html. Whenever possible, you shouldn't choose platform-dependant charset (e.g. windows-1252), but cross-platform ones (e.g. iso-8859-1).
You'll have noticed that coppermine language files come in two "flavours": one in ANSI and one in utf-8 encoding. You won't have to take care of the creation of the utf-8 files, so you'll only have to submit a "normal" language file.
Editors & Tools
In fact you can use nearly any text editor you feel comfortable with that will store your text in ANSI format - in most cases, Windows Notepad (also known as "Editor" in Windows 2000/XP) will be fine.
To find out wether your favorite text editor correctly handles encoding, just start the translation and translate a few lines (preferrably some that contain special chars from you language), save the translation file and close it. Then try to open it with a plain text editor on your system (e.g. Notepad) - if everything's showing up as expected, you should be fine.
Recommended Tools: to see what has changed between the language files of cpg1.2.1 and cpg1.3.x, we recommend using a diff viewer that can hilight the differences in both files. Windows users should go for the great diff viewer WinMerge (available as freeware; 1.95 MB, localizations available as well): You can even edit the files with this tool (352 of 1152 lines have been added or changed). All new/changed lines have a comment at the end like this one: //cpg1.3.0
Full translations only
For the last version of coppermine we used to send out only the lines that had changed in the language files from previous versions to the translators. Although this seemed to be a very easy solution in the first place we later discovered that this method has severe drawbacks:
For those reasons we decided to provide the translators with the most recent english language file along with all existing language files of previous versions for reference and the guide you're currently reading, asking them (the translators: you in this particular case) to translate the whole file. Of course, you can (and are even encouraged to) take a look at the language files from older versions and adopt the stuff that is already in the old version.
Step by step
Here are the steps for the translation in detail:
Escaping single quotes
As you may have noted, all translation strings are put into single quotes - this is the proper way in PHP. If you want your translation to actually contain a single quote (apostrophe), you will have to "tell" PHP that the string that was started with a single quot; doesn't end at the next single quote. This is called escaping in programming languages. PHP uses the backslash (\) to escape characters, that's why it must not be
array('Target address for the 'See more pictures' link in e-cards', 'ecards_more_pic_target', 0),, but
array('Target address for the \'See more pictures\' link in e-cards', 'ecards_more_pic_target', 0),
'no_change' => 'Vous n\\\'avez effectué aucun changement !', //js-alert
Placeholders with %
You'll notice that there are some places in the translation where the text contains a percent-sign (%), followed by a letter. Those combinations mustn't be translated - they'll later be used as specifier arguments for some replacement or formating taking place.
Found a typo/spelling error?
Maybe a translation for your language has already been done, but you're not happy with it: if there are bugs (spelling errors etc.), first check the download section if a fixed version has been done already. If not, report on the board along with your suggestion for a fix, like this:
'some_definition' => 'bar foo',and replace with
'some_definition' => 'foo bar',
Everybody who knows languages knows that there is no such thing as "one correct translation" - there are always different ways to translate words, or whole sentences. Maybe you feel that an existing version of your language file doesn't fit your purpose; probably the translator had another audience /target group, or you want a more formal translation (in many languages there's as well a difference in grammar between formal and casual speech).
Work in progress
Coppermine's a work in progress - as most web-based projects. Maybe your copy of the english.php (that should be the base for your translation) is outdated. That's why it's recommended that you always take a look at the download section and get the most recent english language file (translator version) available before starting your translation (and maybe and updated version of this document as well, since there may be questions turning up later, after initial release of this document). Remember: if an option is not translated, it won't be visible in your language at all.
Initial translation for release
When preparing for a release, the dev team sets up a feature freeze to allow the translators to submit their translations, halting the coppermine development during that period. If you're willing to translate, do so as soon as possible and send your translation back immediately to ensure that the new version of coppermine can be released with your language file.
GauGau (aka Joachim Müller)
- Coppermine dev team -