Coppermine Photo Gallery v1.5.x: Documentation and Manual

Table of Contents


Coppermine has a separate language file that makes the translation of the script much more easy. The language files are stored in the lang directory. The files are unicode-encoded (utf-8).

If you set "Character encoding" to "Unicode (utf-8)" then the script will auto detect the preferred language of your visitors based on what default language is configured in their browsers. If the corresponding language is available in your language directory, it will be used. Otherwise, the default language file will be used.

When the script auto detects the preferred language, it stores the result in a cookie on the visitor's computer. To reset this cookie (and thus force the script to do another auto detection) the user must call this autodetect function with something like:

Using utf-8 (unicode) is strongly recommended - in fact, it's almost mandatory. We (the coppermine dev team members) can hardly see any valid reason for changing the encoding setting for a fresh install - the feature that allows you to change the encoding on the config page basically exists for historical reasons and for backwards compatibility (for users who have started with coppermine long ago and need to maintain their non-unicode database content).

Therefore, the documentation we provide will only explain how to deal with languages when using the default utf-8 encoding. If you decide to use a different encoding, you're doing something that doesn't really make sense and subsequently is not being supported.

In short terms: Do not change the encoding in Coppermine from utf-8 to anything else unless your really, really know what you're doing and if you understand that this decision will mean that you will get unsupported as far as language issues are concerned.

If you have translated Coppermine into a language not already supported or are willing to start translating, please read the translator's guide and follow the instructions and explanations there. Translating Coppermine compeletly into another language is pretty straightforward - you don't need to be a skilled code (in fact, you don't have to be a coder at all).

How languages work in Coppermine

Here's how coppermine determines the language of a user: when accessed, coppermine checks if a user explicitely has set a language preference (which is stored in a cookie on the client). If one is set, coppermine is being displayed in that particular language (of course only if a language file for that particular language is available).

If no individual language preference has been set, coppermine detects the language preference of a user set up in his browser (if the encoding is set to utf-8 and the option "Autodetect language" in enabled in Coppermine's config. If the browser language is (for example) English, then the gallery will display in English. If the browser language is set to Hindi (as an example), while there is no Coppermine language file available for that particular language, then coppermine will fall back to the default language you have set up in Coppermine's config.

As you can see, the determination of the actual language setting is a three step process:

This three-step-process is very helpful: in fact, you only set a default language in Coppermine's config (usually the language the majority of your visitors is speaking) and that's it: if a visitor who speaks another language visits your page, Coppermine's controls will display in his language. Usually, you don't have to provide a language selector on your page (but it's an option in Coppermine's theme to display one if you prefer so). The language selector in fact just adds a parameter to the URL, which then subsequently triggers a cookie to be set on the client. You (as Coppermine admin) can accomplish the same by manually adding the parameter to the URL in the address bar of your browser. Just observe how the URL changes on the your coppermine gallery if you have enabled the language selector in coppermine's theme to get an idea how this works.

If your browser is set to German and you have specified Spanish to be the default (fallback) language, your gallery will display for you in German. To see it in English, add the parameter lang=english to the URL of your gallery in your browser's address bar, so that it looks like this: http://yoursite.tld/your_coppermine_folder/?lang=english. If you do so, you have specified a language preference that is being stored in a cookie that will override the language detection of your prefered language in your browser. To go back to how things were before, simply unset the cookie that stores your preference by entering http://yoursite.tld/your_coppermine_folder/?lang=xxx, where "xxx" is just a language name that doesn't exist (you can use the xxx literally).

If "Autodetect language" has been turned off in coppermine's config, the script will not try to perform the lookup of the browser language. It will display the gallery in the language that the admin has specified as default language. The only thing that will override the default language is an explicit selection of the end user, i.e. if the site admin has chosen to display a language selector (using a dropdown or a flag list) and the visitor has deliberately chosen a language from that list.

Get rid of a particular language

There are many languages available that Coppermine comes with, and the number of language files is increasing, because new language file contributions come in from the coppermine community constantly. As a result, Coppermine comes with a big amount of language files that you can use. Most users will not be aware of this, as their visitors only come from a certain region or country. As a result, you may not even need those many extra languages. If this is the case for you, you can use your FTP app and savely remove the unneeded language files from the "lang"-folder (http://yoursite.tld/your_coppermine_folder/lang/). It is advisable though to keep the English language file under all circumstances.

Language fallback

From cpg1.3.x to cpg1.4.x there used to be a config option named "Fallback to English if translated phrase not found?".

This option has been dropped for cpg1.5.x in favor of a more advanced language fallback mechanism that no longer needs to be configured.

Scope of internationalization

The language files Coppermine comes with can only contain pre-defined strings that compose the controls of your gallery (i.e. the menus). Switching your gallery to another language will have no impact on the custom content that resides in the database (i.e. the category names you have set up or the picture captions). In this aspect, Coppermine is not truely multilingual: there is currently no option available to have the content of coppermine available in more than one language.

The language manager

Starting with cpg1.5.x coppermine comes with a language manager that you can use to fine-tune your language preferences. What the language manager basically does is adding an interface to all the language files that reside in the lang folder. To access the language manager, go to coppermine's config screen, expand the section "Language & Charset settings" and click on the link named "Manage languages". Alternatively, you can manually enter the URL http://yoursite.tld/your_coppermine_folder/langmgr.php in to your browser's address bar.


Use the buttons "Show details" / "Hide details" at the top and the bottom of the page to toggle the display of the language manager between a condensed view (where only the important data is being displayed) and an advanced view (where additional information can be found).
Use the OK button at the bottom of the screen to save changes.


The language manager will display a table with several columns. Those columns have the following meaning: