Coppermine Photo Gallery - Translator's Guide
One of the major features of a Coppermine photo gallery is the fact that all page content can be displayed in different languages, with translations being contained in one file (located inside of the coppermine lang directory ). If you use Coppermine and feel that you would like to give something back to the community, why not start a translation of coppermine for your language?
These are the rules and guidelines for translation to help you get started.
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?
Anyone with a good grasp of a language can, but when a new version of coppermine is being prepped for released, the dev team will contact the translators of previous versions and ask them to translate for the new version, as well. These "original" translators are requested to advise the development team if they are willing and able to do the translation (before actual work on the translation starts). Languages previously assigned to those who respond that they're unable to do the "new" translation or those assigned to translators that fail to reply, over a prescribed time, will be placed on a list on "[Help wanted]: Translations for CPG1.4.x". Anyone who is interested and ready to help with the translation for these "orphaned" languages should reply to the thread and assign the translation to him/herself.
If you are fluent in a language that hasn't been translated yet and hasn't been assigned to anyone, please assign it to yourself.
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).
In cpg1.4.x, the language files in the package come as utf-8 files only. If you can, submit your translation in this encoding. If you have no idea how to do this though, don't worry - submit the file in the encoding you chose, a dev team member will convert it accordingly for you.
Editors & Tools
In fact you can use nearly any text editor you feel comfortable with that will allow you to save your text in the ANSI format - Windows Notepad (also known as "Editor" in Windows 2000/XP) will do just fine.
To determine whether or not your favorite text editor can correctly handle the necessary encoding, start the translation by translating only 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 displays as expected, your editor should work fine.
Recommended Tools: to see what has changed between the language files of cpg1.3.x and cpg1.4.x, we recommend using a diff viewer that can highlight the differences in both files. Windows users should opt for the great, changes in file 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.4.x
Full translations only
Up until version 1.2 of coppermine we only sent out the lines that had changed in the language files from previous versions to the translators. Although this seemed to be a very easy solution and approach, we soon discovered that this method had severe drawbacks:
For these reasons we now provide the translators with the most recent english language file along with all existing language files of previous versions as references. Additionally we provide this guide that you are currently reading, asking them (the translators: you in this particular case) to translate the file in its entirety. Of course, you can (and are even encouraged to) take a look at the language files from older versions and adopt (port) the contents that are already in the old version whenever they apply.
Step by step
Here are the detailed steps for translating coppermine language files:
Escaping single quotes
As you may have already notice, all translation strings are contained between a pair of single quotes or apostrophes - this is the proper method used in PHP. Therefore, if you want your translation to actually contain a single quote (apostrophe), you must "instruct" PHP that the apostrophe (single quote) contained in a text string is part of the string and not the end of the string. For this purpose, a backslash (\) is used to instruct PHP that the character immediately following it is a "string" character and not part of the PHP code, itself. This is called escaping a character, in programing languages. PHP uses the backslash (\) to escape characters, that's why care must be taken to not do this:
array('Target address for the 'See more pictures' link in e-cards', 'ecards_more_pic_target', 0),
but, to do this, instead:
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 also notice that in several places of the language file, there are text that contain a percent-sign (%), followed immediately by a letter. Those combinations must not be translated or separated - they are there intentionally and are used later as specifier arguments, or calls, for variable replacement and/or formating that needs to take 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 to see if a fixed (updated) version has already been submitted. If not, report your finding(s) 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 differences in the way we to translate expressions, or whole sentences. Maybe you feel that an existing version of your language file doesn't suit your purpose; perhaps the translator had another audience /target group in mind, or you want a more formal translation (in many languages there are signifcant difference in grammar and expression between formal and casual speech or text).
Work in progress
Coppermine, like everything else online, is a work in progress. Your copy of the english.php (that should always be used as the base reference file for your translation) may already be outdated. That's why it is critical that you always refer to the download section or Subversion-Repository Language Section to make sure that you have the most recent english language file (translator version) on hand before starting your translation (and maybe even the most updated version of this document, as well, as there may be many questions along the way that need to be addressed in this document after the initial release of this document). Remember: if an option/replacement string is not translated, it will not 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 -