 | Applies to Versions Prior to 1.6
This documentation applies to older versions of CiviCRM. If you are using the current version (1.6 or later) - use this documentation. |
Introduction
One of our goals is to make CiviCRM as usable as possible - which means get it fully localised into any languages that our users find useful and make CiviCRM configurable in all the places that are locale-dependent. To achieve this, CiviCRM uses Gettext for text localisation and configuration options for date/money/address formats and the like. This approach assures that CiviCRM should be easily localisable into wide variety of languages (also the ones using non-Latin scripts/alphabets).
This page explains how to set up CiviCRM to run in one of the other supported languages and how to contribute new and/or updated translations into new languages back to CiviCRM. All of the settings discussed in this section should be set in the civicrm.settings.php file.
Language
The main configuration option responsible for the way CiviCRM "talks" is the CIVICRM_LC_MESSAGES setting. This option sets the language the CiviCRM will use in its user interface; if the underlying server has the proper locale generated, also the full and abbreviated month and day names will be localised properly.
To change the language used in CiviCRM, change the CIVICRM_LC_MESSAGES constant from the default en_US to the proper locale code of the desired language (for example, pl_PL for Polish):
One of the aspects of localisation is the display format of dates. By default, CiviCRM displays the dates in using the American formats by default, but this can be changed by setting the CIVICRM_DATEFORMAT_* options.
The first three CIVICRM_DATEFORMAT_* settings define the format of full dates (dates that contain year, month and day), partial dates (dates with year and month) and year-only dates. The dates are formatted according to the standard POSIX %-prepended sequences.
The (American) defaults look like this:
...which, for the date of 2005-07-13, gets expanded to 'July 13th, 2005', 'July 2005' and '2005', respectively.
Typical European settings would have only the CIVICRM_DATEFORMAT_FULL constant changed; it could look like this:
...which would get expanded to '13 July 2005' (or '13 lipiec 2005' if CIVICRM_LC_MESSAGES is set to pl_PL).
Next to the above date formats, the CIVICRM_DATEFORMAT_DATETIME defines the format of the full date-time display:
...which displays, for example, 'July 13th, 2005 2:26 PM'.
European users might want to redefine this to:
...which would display '13 lipiec 2005, 14:26' instead (note the switch from 12-hour to 24-hour clock and dropping of the AM/PM display).
Besides the above, CiviCRM uses two CIVICRM_DATEFORMAT_QF_* constants that define the order of the date and date-time drop-downs in various CiviCRM forms (for example, contact's birth date or scheduled meetings' date-times):
The above CIVICRM_DATEFORMAT_QF_DATETIME provides the user with six drop-downs: abbreviated month name (%b), day (%d), year (%Y), 12-hour-based hour (%I), minute (%M) and an AM/PM selector (%P).
European users might want to redefine these to:
Which would display the day before the abbreviated month, swich to 24-hour-based hour drop-down (%H) and drop the AM/PM selector.
Countries and Provinces
CiviCRM contains both ISO 3166-1-compliant list of countries and a full, ISO 3166-2-compliant list of provinces (states, departments, voivodships, etc.).
CiviCRM also enables the translation of country and province names, as well as limiting the lists of both countries and provinces for use in a given CiviCRM installation. The format of these options is a comma-separated list of country ISO codes (US for United States, PL for Poland, etc.). If you're not sure what is the code for a given country, you can check it in the civicrm_country table or here.
The CIVICRM_COUNTRY_LIMIT option selects which countries are available to the users. The empty default does not limit the country list; the above example limits the list to United States, India and Poland.
The CIVICRM_PROVINCE_LIMIT option selects which countries' provinces are available to the users. The above default limits the province list to United States' states.
You can also set the default country that should be pre-selected in the country drop-down:
Postal Address Format
In various countries, postal addresses are written differently. The way the addresses are displayed in CiviCRM is defined in the CIVICRM_ADDRESS_FORMAT option. This option is best explained by example. The American default looks like this:
The general rules are as follows:
- Every {
...token...} will be replaced with the token's value (keeping anything else inside the curly braces intact).
- If the value of a given
token is missing, the whole {...} construct will be dropped.
- Any {
non-token} construct will be turned into non-token if, after tokens are replaced, it has content on both sides (i.e., it will be dropped if on the beginning or end of any line). If there's no city, {city}{, }{state_province}{ }{postal_code} will turn first into {, }California{ }12345 and then into California 12345.
- If, after token replacements, there are any consecutive {
non-token} constructs, the first one's contents will replace the whole series. For example, if there's no state_province, {city}{, }{state_province}{ }{postal_code} will first turn into San Francisco{, }{ }12345 and then into San Francisco, 12345.
For example, Polish users, who usually don't write the vovidoship names in the address, might want to change CIVICRM_ADDRESS_FORMAT to:
Currency
CiviCRM 1.3 supports only one currency; the currency can be set via the CIVICONTRIBUTE_DEFAULT_CURRENCY option. This option takes the ISO 4217 currency code ('USD' for US Dollars, 'GBP' for British Pounds, 'EUR' for Euro, etc.).
The format of the monetary amount string (whether to write the currency before or after the amount, whether to use currency symbols like $, £ and € or use the ISO 4217 codes, whether to put space between the currency and the amount) can be controlled with the CIVICRM_MONEYFORMAT option:
The meaning of the % symbols is as follows:
%c - currency symbol ('$'),%C - currency ISO code ('USD'),%a - monetary amount, formatted according to CIVICRM_LC_MONETARY.
The final 'look' of the amount number depends on the CIVICRM_LC_MONETARY setting. As with CIVICRM_LC_MESSAGES, the setting takes a locale (like 'en_US', 'de_DE' or 'pl_PL') and asks the underlying operating system to format the amount accordingly:
The amount of 1234567 dollars and 89 cents will be displayed as '1,234,567.89' with an 'en_US' locale, as '1.234.567,89' with a 'pl_PL' one and as '12,34,567.89' with an 'en_IN' one.
Helping with CiviCRM Localisations
If your language is not yet supported, you can take the matter into your own hands and help us translate CiviCRM.
Gettext
For CiviCRM localisation we decided to use the standard OpenSource approach of using Gettext. This means that all of the localisable strings (pieces of text) appearing anywhere in CiviCRM are kept in one 'POT' file (civicrm.pot), which serves as a 'template' for different 'PO' files (civicrm.po) - one for every language. This way, the fact that CiviCRM is localised into a given language is equivalent to the fact that there exists a civicrm.po file for the language in question.
The drupal-civicrm.pot File
Besides civicrm.pot file (and the derived civicrm.po files) there's a small drupal-civicrm.pot file (and the derived drupal-civicrm.po files, as well). This file contains a couple of strings that are Drupal-specific.
If you'd like to have the Drupal's CiviCRM menu items localised, simply enable the locale module in Drupal's administration interface, add your language in the localization section and import the drupal-civicrm.po file there.
Web-based Localisation
The easiest way to translate CiviCRM is via our Pootle installation. If your language is not yet defined there, please contact us and we'll add it right away.
After creating an account in Pootle select the language you'd like to work on and start translating. When you finish (or believe that the translation is updated significantly) let us know, and we include the new/updated PO file in CiviCRM.
PO-file-based Localisation
If you prefer to translate CiviCRM on your own, you can do this by downloading (from the translations page) the right PO file for your language. If your language's PO file is not generated, you can download the POT template and generate the proper PO file, or ask us to do it for you.
Once you have the proper PO file, you can use any standard Gettext tool to translate the contets (or edit it with any simple text editor). The most popular translation tools are:
After translating/updating the translation, please send the result to us, so we can include it in CiviCRM. If possible, please keep the file encoded in UTF-8 charset.
The crm-translators Mailing List
If you'd like to do any work on CiviCRM localisation or have any feedback you'd like to share with us, it would be great if you joined the crm-translators mailing list.
E-mail
