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.
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:
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.5.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.
Many languages have special alphabets other than the latin set, or have additional characters (like ä ß à á â ã å æ ç þ ð ø). Many of these special chars have what are called html equivalents (e.g. ä for ä), but you must not use these html equivalents of your special language characters when doing your translations, as unwanted side-effects may appear with the usage of JavaScript!
No matter what encoding you use to contribute your translation, the encoding with which your translation contribution will be added to the package will be utf-8. In other words: some coppermine developer will have to transform your proprietary encoding to utf-8 before it can be used, so if you can you should use utf-8 in the first place.
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 utf-8 encoding. You do not have to concern yourself with the creation of the utf-8 version if you have no idea how to accomplish this - the dev team will take care of that. However, your language file will finally go into the package as UTF-8 file. Subsequently, if you want to create a perfect language file, create it in utf-8 in the first place.
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.
Of course, you're welcome to use a more powerfull editor and use (if you can) utf-8 as encoding.
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.
The drawback when using one of the tools that come with the operating system Microsoft Windows out of the box is the fact that they haven't been created with Unicode (utf-8) support in mind, but mostly catter for the proprietary ANSI format that was introduced way back with MS DOS. Subseuqently, if you language is using non-latin characters you might have a hard time to test the language file in your testbed before submitting it.
Recommended Tools: to see what has changed between the language files of cpg1.4.x and cpg1.5.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; 3 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.5.x.
If you need a powerfull, free editor for Windows, the dev team recommends using Notepad++.
For a full list of suggestions, please review "Tools recommended by the devs"
A text processor like MS Word is definitely not the right tool to handle a language file, as it tends to "beautify" the code within a language file, which will break the language file.
If you're concerned to install yet another tool on your operating system, then don't be alarmed: many of the editors (like Notepad++) come in packages that allow you to run the editor without installation: subsequently, your operating system doesn't get slowed down or cluttered by yet another application.
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.
This does of course not mean that you need to provide a full translation as much as the completeness of your contribution is concerned: we understand that it's a lot of work to come up with a translation for each string in a language file, that's why it's acceptable as well if you only provide a partial translation into your language, with part of the language file remaining in English. Please make sure though to tell us that you are providing a partial translation only.
Here are the detailed steps for translating coppermine language files:
Translate the entire language file as described - you'll find your way around in no time, even if you're not a seasoned PHP coder.
As you may have already noticed, 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:
$lang_errors['access_denied'] = 'You don't have permission to access this page.';
but, to do this, instead:
$lang_errors['access_denied'] = 'You don\'t have permission to access this page.';
Things are a bit more complicated if the output is to be used not only in plain HTML, but in JavaScript, as well. Single quotes that appear in the HTML output of the language file must also be escaped for use in any JavaScript routine with a backslash as well. That's why specific lines in the language file that will be used as JavaScript in Coppermine's output have been tagged with a comment at the end of the line, which reads: //js-alert. If you intend to have a single quote in the final output, you'll have to add 3 backslashes in front of the single quote, as in this example:
'no_change' => 'Vous n\\\'avez effectué aucun changement !', //js-alert
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.
$lang_rate_pic['rating'] = '(Current rating : %s / %s with %s votes)';
What actually happens is that in the code (usually using the PHP command sprintf; refer to the type specifier specifications for details) there is a replacement, where the placeholder (usually %s) is being replaced with some content dynamically.
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:
in lang/yourlanguage.php search for
$lang_example['some_definition'] = 'bar foo';
and replace with
$lang_example['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).
Please do not flame (berate) the original translator on the board, but provide an alternative translation along with details on what you changed and for what target audience your version is intended.
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 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.
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.
We understand that coming up with a full translation can be quite a difficult task to accomplish, so you might be tenpted to skip the hard work and go for a solution that may seem to be easier at first sight: you might want to use a language file that was created for a previous version of coppermine (e.g. cpg1.4.x) and built on that file (instead of doing as suggested in this section of the docs and starting your work based on the current version of lang/english.php).
Although the "lazy" method may seem to be attractive, you can't use it for various reasons. To mention only a few of them:
$lang_meta_album_names = array( 'random' => 'Random files', 'lastup' => 'Last additions', 'lastalb'=> 'Last updated albums', 'lastcom' => 'Last comments', 'topn' => 'Most viewed', 'toprated' => 'Top rated', 'lasthits' => 'Last viewed', 'search' => 'Search results', 'favpics'=> 'Favorite Files', //cpg1.4 );to
$lang_meta_album_names['random'] = 'Random files'; $lang_meta_album_names['lastup'] = 'Last additions'; $lang_meta_album_names['lastalb'] = 'Last updated albums'; $lang_meta_album_names['lastcom'] = 'Last comments'; $lang_meta_album_names['topn'] = 'Most viewed'; $lang_meta_album_names['toprated'] = 'Top rated'; $lang_meta_album_names['lasthits'] = 'Last viewed'; $lang_meta_album_names['search'] = 'Image search results'; $lang_meta_album_names['album_search'] = 'Album search results'; $lang_meta_album_names['category_search'] = 'Category search results'; $lang_meta_album_names['favpics'] = 'Favorite files'; $lang_meta_album_names['datebrowse'] = 'Browse by date'; //cpg1.5
This should make clear that you should not start editing a language file for cpg1.4.x and try to port that for cpg1.5.x - you'd have to perform edits for each and every line.
Instead, we recommend doing as suggested and using a copy of english.php from cpg1.5.x and use that as a base for your new translation. We recommend to open a copy of the outdated language file as well in your editor and just copy individual strings from the outdated language file to your fresh copy.
As suggested above, all contributions are welcome. While it already is a huge task to come up with a coppermine language file, it's even a greater task to come up with a full translation of the coppermine documentation. That's one of the reasons why the documentation that used to be one monolithic block (one huge HTML page) has been split up into separate files starting with cpg1.5.x.
For the benfit of your community, you're asked to translate part of the documentation (or maybe even all of it) as well. To accomplish this, do the same as suggested above: make sure that your translation doesn't already exist by checking the SVN repository and if there already is a discussion on the forums going on. If there is no such activity, go ahead and start your translation.