Skip to content
Snippets Groups Projects

Administrator Guide

Last edited by bgm

Overview

This administrator guide explains how to set up CiviCRM to run in one of the other supported languages. This includes the installation of language files (civicrm-l10n.tar.gz), how to update those files between releases, the various language settings and performance tips.

This guide is part of the translation documentation, which includes more information on support, community and other pointers.

CiviCRM installation in another language than US-English

For WordPress, please refer to the official CiviCRM on WordPress installation documentation.

To install CiviCRM in another language, you must first download and copy the translation files to the correct location on your server:

  • Download the translations distribution - civicrm-<version>-l10n.tar.gz - from the CiviCRM downloads page. This compressed file contains all files for the latest available translations.
  • Uncompress the file 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 French translation files will located in /civicrm/l10n/fr_FR).
    • The sql directory contains files requires for the initial installation of CiviCRM. It is important to install in your target language so that the default CiviCRM configurations are set in the correct language. Otherwise you will have to review and reconfigure many options.
  • Copy this l10n directory, together with all its subdirectories into your CiviCRM root directory. Note: if creating the l10n folder manually, the first letter is a lowercase 'L', as in 'localization'.
    • 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/.
    • 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/.
    • 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/.

Changing the default CiviCRM language after installation

The best option is to install directly into the language you wish to use. If you had not initially installed the localization files, we recommend to re-install with those files installed.

However, you can still change the language later on:

  • Go to Administer > Localization > Languages, currencies and locations
  • Select the new default language.
  • Update the default currency, money formatting options, default country, etc.

You will also probably want to update the date and time formats:

  • Go to Administer > Localization > Date Formats.

Finally, you may notice that many other options in CiviCRM will not be correctly translated:

  • Individual prefixes (Mrs, M, etc)
  • Gender options (M, F, other)
  • Address Location Types
  • Some fieldsets in the "Edit Contact" screen

These are known in CiviCRM as Option Values, and there are many of these.

To avoid having to change every single setting, you can install the following extension: fixoptiontranslations. Once the extension is enabled, all options will have been translated. The extension can then be uninstalled and removed.

Updating translation files

The easiest way to update your translations regularly is to use the "l10n update" extension: https://github.com/cividesk/com.cividesk.l10n.update/

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

Every night, around 2 AM (North American Eastern Time), the CiviCRM website packages updated translation files.

They are available at the following address:

https://download.civicrm.org/civicrm-l10n-core/mo/xx_XX/civicrm.mo

For example, for Spanish:

wget https://download.civicrm.org/civicrm-l10n-core/mo/es_ES/civicrm.mo

For extensions:

wget https://download.civicrm.org/civicrm-l10n-extensions/mo/cdntaxreceipts/fr_CA/cdntaxreceipts.mo

Storing translation files in another directory

By default, CiviCRM looks in [civicrm.root]/l10n for translation files. Since CiviCRM 5.23, there is a new setting available to store those files in another directory. This can be convenient when files are updated regularly, or when using the l10nupdate extension, which requires the files to be web-writable.

More information, see PR15408.

As of this writing, this setting only applies to core translations, not extensions.

Native gettext

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.

Since CiviCRM 4.2, it is possible to use native gettext. This may require some changes to your hosting environment and is therefore recommended mainly for sites hosted on dedicated environments (VPS or dedicated server, it may not work on shared hosting).

To enable it:

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

Debian/Ubuntu systems can enable locales by typing:

dpkg-reconfigure locales

Note: the "UTF-8" variant of the locale must be enabled. For example: "fr_FR.UTF-8".

Apache or php-fpm must be restarted after adding a new locale.

Finally, uncomment the following to the civicrm.settings.php:

define('CIVICRM_GETTEXT_NATIVE', 1);

Comments

    Please register or sign in to add a comment.