Coppermine Photo Gallery 1.3.x - Translator's Guide

Translators wanted!

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...

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.3.x"? Please read the thread carefully to check if the translation has already been done or is in the works - it'd be a pity if two translators went through all the work submitted two versions of the same language.
  You may find additional info there that didn't make it into this document you're reading...

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.

Character encoding

Many languages have other alphabets than latin, or have additional characters (like ä ß à á â ã å æ ç þ ð ø). Many of those special chars have html equivalents (e.g. ä for ä), but you must not use those html equivalents of your special characters in 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';

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:

• The translators can't test their code immediately - if only one single quote is missing, the whole file won't work
• Corrections had to be send back on forth between the dev team and the translators very often
• The dev team had to merge the old language files with the bits that were newly translated - this resulted in a huge additional workload for the dev team, slowing down the new release and keeping them from what they do best
• The translators don't know the context some lines appeared in, making it impossible to give correct translations

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:

1. open english.php with your text editor
2. Save the file immediately after opening with a different filename (to make sure you can always take another look at the unmodified english language file for 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 name of your language as filename, everything lowercase, 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' => '',Your email address you want to 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 actually fills php variables/arrays with 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('CONFIG_PHP')) $lang_config_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 whole language file as described - you'll quickly find your way around, even if you're not a PHP coder.

5. Test your translation: upload your language file to the server and browse you gallery, adding and 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, especially creating, 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'll be surprised what they will find out...
7. Send your translation as attachment to gaugau AT users DOT sourceforge DOT net. Please make sure to have a proper subject line saying "Coppermine Translation: XXX language file" (I get so much spam these days - if the subject line doesn't look ok for me I might accidentally delete the email without reading it).
   You can send the attachment as php file or you can put it inside a .zip archive, but please don't use exotic archive formats like .rar

Special issues

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

array('Target address for the \'See more pictures\' link in e-cards', 'ecards_more_pic_target', 0),

Single quotes in JavaScript (//js-alert)

Things get even a bit more complicated if the output will not be only in plain HTML, but in JavaScript, as you have to escape the single quote in JavaScript with a backslash as well. That's why I marked the lines in the language file that will be JavaScript in Coppermine output later with a comment at the end of the line, saying //js-alert. If you want to have a single quote in the final output, you'll have to add 3 backslashes in front of the single quote, like in this example:

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

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 if a fixed version has been done already. If not, report 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 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).
Please do not flame the original translator on the board, but provide an alternative translation along with details on what you changed and for whom your version is intended.

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.