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

# Languages

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: `http://yoursite.com/coppermine_dir/index.php?lang=xxx`

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:

- user preference (cookie)
- browser setting
- coppermine config setting

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.

### Controls

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.

### Columns

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

- #### Default

  Specify the default language for your gallery; this record is identical to the one you can pick on the config panel using the option "Default Language".
  You can only pick languages that are enabled in the first place. Those that are not enabled will be greyed out.
  The default language will be the one that is used if the visitor's prefered language could not be detected or if the visitor's prefered language doesn't exist as coppermine language file.

- #### Language name

  The column "Language name" consists of three sub-columns. Each of those columns contains a text field where you can change the default.

  - ##### English

    The language name in English. It's recommended not to change this record.

  - ##### Native

    The language name in the native language, i.e. the word "Français" that means "French" in French

  - ##### Custom

    If your language or the language of the majority of you visitors will be another language than English and you have a language selector in place, you can specify the language names in your language.
    Example
    This is a possible example if your gallery catters for a German audience, with the language names in German entered into the custom field:

    English | Native | Custom
    Bulgarian | Български | Bulgarisch
    Czech | Česky | Tschechisch
    English (US) | English (US) | Englisch
    Finnish | Suomea | Finnisch
    French | Français | Französisch
    German (informal) | Deutsch (Du) | Deutsch
    Greek | Ελληνικά | Griechisch
    Polish | Polski | Polnisch
    Russian | Русский | Russisch

    If text is entered into the "Custom"-column, it will take precedence over the pre-populated columns.

- #### Flag

  The flag column contains a dropdown field where you can specify another flag that you want to use to represent your language. The flag icon you pick will be only applicable if you enable a language selector in your custom theme (which is not not recommended and off by default). Usually, the flag can be left alone if there is a clear correlation between your country and your language.
  Take German as an example: the flag of Germany represents German by default, but of course German is spoken in other countries as well, e.g. in Austria and Switzerland. So, if you're from Austria and have a language selector on your page you might want to change the flag representing German from Germany to Austria as well.

- #### Language file

  There are two sub-columns inside the language file column:

  - ##### Available

    As most other coppermine settings, the language preferences are being stored inside the database as well.
    - If there is only a database record for a particular language, but the corresponding language file isn't there, there will be a stop-icon in this column.
    - If there is both a database record as well as a language file, the OK-icon will be displayed
    - If there is a language file, but so far there has been no database record for that file, a plus-icon will be displayed. Submit the form to create a record in the database as well.
    You can only enable a language if the corresponding language file exists.

  - ##### Complete

    The column "Complete" is a result of a detailed check of each file:
    - If the language file has been designed for your version of coppermine, an OK-icon will be displayed in this column.
    - Otherwise, if your language file has been designed for a pervious version of coppermine, a cancel icon will be displayed instead. This doesn't necessarily mean that you can't use a particular file - missing translations (if any) will shine through in English instead.

- #### Enabled

  This is the most important column of the entire screen: here you determine if a particular language will be taken into account, i.e. if the language can be used by visitors. This is independant of the existence of a language selector: if a particular language isn't enabled, it's as if the language file didn't exist in the first place.