Skip to end of metadata
Go to start of metadata


This page is part of the documentation on Internationalisation and localisation. This page explains how to set up CiviCRM to run in one of the other supported languages. For more information on how to contribute new and/or updated translations into new languages back to CiviCRM, see the Resources for Translators.

If you have any questions, please post on the Internationalisation and localisation forum.

Using CiviCRM in another language than US-English

To configure CiviCRM to use an existing translation:

  1. Download the translations distribution - civicrm-<version>-l10n.tar.gz - from the CiviCRM downloads page. This tarball contains all files for the latest available translations.
  2. Uncompress the tarball and you will see a directory called civicrm, containing two subdirectories called l10n and sql. The l10n directory contains a set of sub-directories named using their local codes. (Example: the Canadian French translation files will located in /civicrm/l10n/fr_CA). (The sql file can be ignored as this is only required during initial installation.)
  3. Copy this l10n directory, together with all its subdirectories into your CiviCRM codebase root directory. (note if creating the l10n folder manually it should be ell-ten-n, not capital-I-ten-n)
    1. For Joomla this would be site_root/administrator/components/com_civicrm/civicrm.  So if you wanted the en_GB language it would look like this site_root/administrator/components/com_civicrm/civicrm/l10n/en_GB/
    2. For Drupal this would be site_root/sites/all/modules/civicrm.  So if you wanted the en_GB language it would look like this site_root/sites/all/modules/civicrm/l10n/en_GB/
    3. For Wordpress this could be site_root/wp-content/plugins/civicrm/civicrm. Note the double civicrm! So if you wanted the en_GB language it would look like this site_root/wp-content/plugins/civicrm/civicrm/l10n/en_GB/

To enable the default language
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Localization » Languages, Currency, Locations
  3. You should now be able to see and select all the localization options in the Default Language and drop-down menu. If you don't, and instead can just see the default 'English (United States)' option, check the preceding steps as the drop-down options are set by the directories under your l10n directory. Also be sure to confirm that the l10n directory is correctly named as l10n (that is: el-ten-en and not eye-ten-en).

Your CiviCRM screens should now appear in the selected language. If the underlying server has the proper locale generated, the full and abbreviated month and day names will also be localised properly.

Any text that has NOT been translated in the translation files will appear in the default English language. If you see English text after setting a different language, you may need to add to the translation. Refer to the section on helping with CiviCRM localisations below.

Updating your translation files

The civicrm-<version>-l10n.tar.gz files are updated when there is a new CiviCRM release. Languages are included in this file when they reach 20% completion.

You may need to update your translation files before the next release for various reasons:

  • you are participating to improve the translation of CiviCRM in your language,
  • a string was badly translated and you're impatient to fix it,
  • a string had bad markup (ex: the link syntax or variable placeholder was mistyped, causing bugs, particularly odd javascript bugs, parts of the screen that cannot be loaded, etc).

If that is the case, you have a few options:

Updating your translation files using the "l10n update" extension (Recommended)

The easiest way to update your translations regularly is to use the "l10n update" extension:

The "l10n update" extension will do a daily check to update the translation files for CiviCRM core, as well as for extensions.

Under the hood

Every day at 10h00 US Pacific time, the CiviCRM website packages updated translation files. They are available at the following address:

For example, for Spanish:


Updating your translation files manually using Transifex

If you do not want to wait up to 24 hours in order to get the latest translation strings, you can download the strings from Transifex and "compile" (package) the files manually. This is a bit more technical and requires a few tools from the command line (GNU/Linux, Mac OSX, and Windows if you are courageous):

  • you must have a Transifex account (you can signup for free).
  • the "gettext" utilities must be installed (the "msgfmt" command should be available). Under Debian and Ubuntu, you can "apt-get install gettext".
  • you will also need "git" and the Transifex command line client.

After installing the required programs, clone the l10n repository:

This may take a bit of time, since the repository has become rather big. It will include the strings for all the available languages.

When it is ready, update the translation files in order to get the latest strings:

You can also update only a specific language:

When this is ready, you can compile the text files (*.po) into the binary gettext format that is used by CiviCRM (

The above compiles the files for all languages. You can also compile only a specific language, for example:

After compiling, you should have an l10n/xx_XX/ file. Replace the existing file with the new compiled one. If you then select the proper language under Administer »  Localization  » Languages, Currency, Locations, the strings should start being translated.


On Microsoft Windows,we strongly encourage you to use poedit.

For more information, see:,35212.0.html


If you have problems compiling your translation, please post on the internationalization and localization forum.

Localization Settings

Localization cheat sheets

If you are installing CiviCRM in a country other than the US and you want help with tips, tricks and common gotchas for your country, have a look at the Localisation cheat sheets which aim to document common tasks that you'll want to carry out to make your CiviCRM work best in your country.

Note: these cheat sheets are fairly new so it might be that there isn't one in your language - if that is the case, please consider starting one for your country.  Your fellow countrymen and women will appreciate it! (smile)


Currency and Monetary Display Formats

The default currency in CiviCRM is USD, but you can select the several appropriate currencies for your site.

You can also control the way that monetary values are displayed - both the number format and the arrangement of currency symbols relative to the amount.

The 'look' of the numeric value (amount) depends on the currency settings. You can directly provide thousands separator (US default: comma) and decimal delimiter (US default: dot).The format of the complete monetary display (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 Monetary Display option:


Default US Monetary Display

The meaning of the % symbols is as follows:

  • %c - currency symbol ('$'),
  • %C - currency ISO code ('USD'),
  • %a - monetary amount, formatted according to selected Monetary Locale.

To modify Currency Settings:
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Localization » Languages, Currency, Locations
  3. Update the corresponding fields in the Language and Currency section as needed and Save your changes.

Import/Export Files

The default import/export field separator in CiviCRM is "," but you might need to change it to ";"  or "." or "|" based on the kind of CSV files you are using.


To modify Import/Export Field Separator
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Localization » Languages, Currency, Locations
  3. Update the field "Import / Export Field Separator" in the Language and Currency section and Save your changes.

Countries and Provinces

The installed CiviCRM database contains both an ISO 3166-1-compliant list of countries, and a full, ISO 3166-2-compliant list of provinces (states, departments, voivodships, etc.).

You can configure the selections provided in address input fields for your installation (based on the geographic distribution of the address records you plan on storing). You can:

  • Set a Default Country. This country will be selected by default when entering new addresses.
  • Limit the list of Available Countries offered in Country drop-down lists on address input forms.
  • Limit the Countries whose States and Provinces are offered on address input forms.


To modify Countries and Provinces
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Localization » Languages, Currency, Locations
  3. Update the fields in the Contact Address Fields - Selection Values section as needed and save your changes.


Postal Address Formatting

In various countries, postal addresses are written differently. CiviCRM allows you to modify the default United States format to meet the requirements of your installation.

To modify Address Settings
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Localization » Address Settings
  3. Update formatting patterns as needed and Save your changes.

This option is best explained by example. The American default looks like this:

Default Address Format


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{ }12345and 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 the Address Formatting to:


Address Format without Province


Address Parsing

CiviCRM supports optionally enabling address parsing so that the various elements of a civic address can be automatically separated from each other as they are entered in the Street Address field.

Currently, address parsing supports extracting the street number, the street number suffix, and the unit from the address, but not the street type and street direction. Parsing is especially useful when you wish to produce reports that can be sorted for walk lists for street canvasses.

CiviCRM supports localization of civic address parsing. Initially, Canadian English and Canadian French addresses will be supported; they differ from American English addresses by supporting the unit before the street number (i.e. 2-123 Main St rather than 123 Main St, Unit 2), and putting a comma after the street number and before the street type in French (i.e. 2-123, rue Principale). There is no configuration options provided: when these locales are active, their address style will be used, otherwise the default American English one will be used. To include address parsing support for more locales, contact a provider on the Professional Services section.

Specifying the local to be used for address parsing is available to programs through the API by calling CRM_Core_BAO_Address:parseStreetAddress.

To enable Address Parsing
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Localization » Address Settings
  3. Click on Street Address Parsing in the Address Editing fielset and Save your changes.

Date Formats

One of the aspects of localization is the display and input format for dates. By default, CiviCRM displays the dates using the American formats, but this can be modified to match your preferred formats.

You can define the formats for the following types of date display:

  • Complete Date and Time (dates that contain year, month, day and time)
  • Complete Date (dates that contain year, month and day)
  • Month and Year
  • Year Only


    Date Formats Use POSIX Sequence Codes

    Date formats are specified using the standard POSIX %-prepended sequences. You should review these formatting codes and the Date Formatting Examples below before attempting to modify the date formats. You can also find these codes here

    To modify Date Format
    1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
    2. Go to Administer » Localization » Date Formats
    3. Update formatting patterns as needed and Save your changes.

Date Format Examples

The default American format for Complete Date and Time is:
%B %E%f, %Y %l:%M %P
...which, for the date of 2005-07-13, gets expanded to 'July 13th, 2005 2:26 PM'.

European users might want to redefine this to:
%E %B %Y, %k:%M
...which would display '13 July 2005, 14:26' instead (note the switch from 12-hour to 24-hour clock and dropping of the AM/PM display).

The default American format for Complete Date is %B %E%f, %Y
...which, for the date of 2005-07-13, gets expanded to 'July 13th, 2005'.

Typical European settings would have this format changed; it could look like this:
%E %B %Y
...which would get expanded to '13 July 2005' (or '13 lipiec 2005' if user language is set to Polish - pl_PL).

The Date Input Field formatting options 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 default layouts are:
Complete Date and Time: %b %d %Y, %I : %M %P
Complete Date: %b %d %Y

These defaults provide the user with six drop-downs: abbreviated month name (%b), day (%d), year (%Y), 12-hour-clock hour (%I), minute (%M) and an AM/PM selector (%P).

European users might want to redefine these to:
Complete Date and Time: %d %b %Y, %H : %M
Complete Date: %d %b %Y

Which would display the day before the abbreviated month, switch to 24-hour-based hour drop-down (%H) and drop the AM/PM selector.


Name and Greetings Formats

Conventions for handling components of persons' names vary considerably between different languages and regions. Consequently, you might need to adapt the Individual Display Name Format.

Starting with CiviCRM 4.5, you can also configure which name fields show up in the input forms for editing individual contact records, in the Editing Contacts section (also under Display Preferences).


To modify Display Name Format
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Customize Data and Screens » Display Preferences
  3. Update formatting patterns as needed and Save your changes.

Sets of Postal Greeting, Email Greeting, and Addressee formats can also be configured. Traditionally, you would set up at least a default format (which is automatically selected for newly created contacts) for each of these; and optionally you could add further standard formats (e.g. to reflect different levels of formality), which can be explicitly selected for specific contacts.

However, many languages/regions have more complex rules for composing greetings, which can't be covered adequately with only a simple default format. Thus CiviCRM 4.5 introduces another approach: complex formats using conditionals to derive the specific greeting from other contact data fields. These complex formats are defined the same way as the simple formats, but you can use the more powerful Smarty template syntax now.

To modify Greetings and Addressee Format
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions").
  2. Go to Administer » Communications
  3. Add/edit the greetings and addressee format as needed and Save your changes.

 To facilitate this new approach, CiviCRM 4.5 introduces a new dedicated Communication Style field. This allows using only a single default format for each greeting type, with conditionals that adapt the greeting to different formality levels according to the Communication Style field. The benefit over just using several simple formats to choose different communication styles, is that the explicit information in the dedicated Communication Style field can also be used for other purposes, such as conditionals in Message Templates.

If you don't need the explicit Communication Style field, you can disable it by removing all items in the Communication Style Options.

To modify Communication Style
  1. Login to CiviCRM (as a user with "administer CiviCRM permissions")
  2. Go to Administer  » Communications » Communication Style Options
  3. Add/edit options as needed and Save your changes.

For an example how to use all these options properly, you can check the Recipe for German Name and Greetings Handling.

"Inherit CMS language" and regional translations (ex: fr_CA)

If you have a multi-lingual site and you are using the "inherit CMS language" configuration option, but wish to, for example, use fr_CA instead of the default fr_FR (for French), you can define a constant in your "civicrm.settings.php" to override the default behavior.
See CRM-9558 for more information.



Using native gettext support / setlocale

Gettext is the mechanism by which strings are translated. By default, CiviCRM uses the PHP-Gettext implementation. This implementation can cause a 20-30% performance loss on servers who do not have correct caching (such as APC) configured.

Starting CiviCRM 4.2, you can also use native gettext. Since this may require some changes to your hosting environment, it is recommended mainly for sites hosted on dedicated environments (VPS or dedicated server, not shared hosting).

To enable it:

  • your PHP must have gettext support compiled in (it usually is the case, see your phpinfo() for more information). Debian and Ubuntu include it by default.
  • your operating system must have the locale enabled. For example, on Linux-based systems, this is in /etc/locale.gen, or you can type the following:

    • locale -a

  • Debian/Ubuntu based systems can enable locales by typing:

    • dpkg-reconfigure locales
    • you must restart Apache after adding a new locale (/etc/init.d/apache2 restart)
  • Add the following to your civicrm.settings.php: define('CIVICRM_GETTEXT_NATIVE', 1);

Note: your must enable the "UTF-8" variant of the locale. For example: "fr_FR.UTF-8".


  • None
  1. May 16, 2017

    Can anyone clarify what the sql files are for. this is mentioned only once "Uncompress the tarball and you will see a directory called civicrm, containing two subdirectories called l10n and sql" but isn't mentioned again, which makes me wonder either 'why are they there' or 'what haven't i done with them that I should have done'

    1. May 16, 2017

      The sql files are for the initial installation of CiviCRM, during which many configuration settings are defined: individual prefixes/suffixes, address location types, genders, pretty much any list of options (civicrm_option_{group,value}). Once CiviCRM has been installed, they aren't necessary anymore.

      I'm not sure what level of detail should be mentioned? It's easy to get side-tracked by the internals.