Coppermine Photo Gallery - Translator's Guide

Translators wanted!

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.

Why translate?

• To give something back to the community
• Because you needed the translation anyway...
• To see your name on the credits list
• To promote your services (being linked from a relevant page like the Coppermine team/credits page will increase your page rank as well)
• Because you're a nice person

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:

• Is the language you're looking for already included in the lang-folder of the coppermine package you downloaded?
• Is the language file already available as separate download in the language section of the coppermine project page? Visit http://sourceforge.net/project/showfiles.php?group_id=89658&package_id=98540
• Has someone volunteered to do the translation recently on the Coppermine board thread "[Help wanted]: Translations for CPG1.4.x"? Please read the thread carefully to check if the translation has already been done or is in the works. We appreciate your intent, and we also value your time, so it'd be a pity if you and another translators went through all the work to submit two versions of the same language.
  You may find also find additional information there that didn't make it into this document ...

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.

Character encoding

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!

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';

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:

• The translators couldn't test their code immediately - if a single quote is missing from the language file, the entire file won't work
• Too often, corrections had to be sent back and forth between the dev team and the translators
• The dev team had to merge the previous language files with the bits that were newly translated - this resulted in an additional heavy workload for the dev team, slowing down the new release and keeping them from what they do best
• The translators didn't know the exact context that some lines appeared in, making it impossible to provide the proper translations

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:

1. open english.php with your text editor
2. Save the file immediately after opening under a different filename (to make sure you always have an unmodified english language file that can be used as a reference) - the filenames of the language files will decide how the language name will look in the dropdown list of the coppermine backend - use the english(roman characters)name of your language as the final filename, using lowercase in the name with no spaces or special chars (except "-" and "_" and the dot to mark the extension. If the language name itself isn't self-explanatory, add info with an underscore.
   Examples: german.php, italian.php, greek.php, brazilian_portuguese.php
3. Edit the header info (example content is highlighted):
   // info about translators and translated language
   $lang_translation_info = array(
   'lang_name_english' => 'German',The name of your language in English
   'lang_name_native' => 'Deutsch',The name of your language in your mother tongue
   'lang_country_code' => 'de',The country code representing your language. If your language is spoken in several countries, choose the one most people will relate to your language
   'trans_name'=> 'GauGau',Your name (or rather the name you would like to appear on the credits page)
   'trans_email' => '',If you prefer, your email address, which would normally appear on the credits page, can be left blank
   'trans_website' => 'http://gaugau.de/',Your website (goes to credit page). If you specify none, your profile page will be displayed instead
   'trans_date' => '2004-03-17',The date you translated/last changed the language file
   );
   Fill in the data you want to appear on the credits page as shown in the example above.
4. The coppermine language file is used to dynamically replace php variables/arrays with the correct content. There are different ways those arrays are being filled - as shown in these examples (stuff that needs to be translated is highlighted):
   
   • $lang_day_of_week = array('Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat');A plain list of values in an array. Translate each word inside the quotes.
   • $lang_yes = 'Yes';
   A value is assigned to a variable. Translate everything inside the single quotes.
   • $lang_cat_list = array(
     'category' => 'Category',An array with key => value pairs. Only translate the value, the key must be left alone!
     'albums' => 'Albums',
     'pictures' => 'Files',
     );
   • if (defined('ADMIN_PHP')) $lang_admin_data = array(Cascaded/multi-dimensional arrays. Translate the very first entry in each line.
     'General settings',
     array('Gallery name', 'gallery_name', 0),
     array('Gallery description', 'gallery_description', 0),
     array('Gallery administrator email', 'gallery_admin_email', 0),
     array('Target address for the \'See more pictures\' link in e-cards', 'ecards_more_pic_target', 0),
     array('Gallery is offline', 'offline', 1),
     //...
   • $lang_register_disclamer = <<<EOT
     While the administrators of {SITE_NAME} will attempt to remove or [...]
     <br />
     By clicking 'I agree' below you agree to be bound by these conditions.
     EOT;Var definitions using the heredoc syntax: make sure to only translate the plain text, leaving everything in curled braces and all html tags intact

   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.

5. Test your translation: upload your language file to your server and browse your gallery, adding an additional parameter lang=your_language_name to the URL (e.g. http://yoursite.tld/coppermine/?lang=german). Make sure to test as many aspects as possible from the file you creaeted, especially in the creation, renaming and deleting of users,categories, albums, pictures and comments.
6. Proof-reading: if you can, let someone else (preferably non-tech user) test your translation as well. You might be surprised as to what they will discover...
7. Send your translation as an attachment to gaugau AT users DOT sourceforge DOT net ( gaugau@users.sourceforge.net ). Please make sure to include a proper subject line saying "Coppermine Translation: XXX language file" (Devs often receive so much spam mail these days that if the subject line of an email doesn't look appropriate for him/her, the email may be deleted without having ever been read.
   You can send the attachment as a php file or you can put it inside of a .zip archive, but please don't use other exotic archival formats such as .rar, .ace, etc.

Special issues

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),

Single quotes in JavaScript (//js-alert)

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

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.

Language versions

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:
in lang/yourlanguage.php search for

  'some_definition' => 'bar foo',

  'some_definition' => 'foo bar',

Another translation?

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.

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.