Skip to content

Server Locale Requirements

Jump to bottom
George Dawoud edited this page Dec 27, 2025 · 2 revisions

Server Locale Requirements

Overview

ChurchCRM uses GNU gettext for internationalization and translation support. For translations to work properly, the server operating system must have the required locales installed and enabled. This is a critical system-level requirement that must be configured before ChurchCRM's multilingual features will function.

Why Server Locales Are Required

The PHP gettext extension relies on the operating system's locale libraries (specifically libc on Linux) to perform translations. When you select a language in ChurchCRM:

  1. ChurchCRM calls PHP's setlocale() function with the selected language code
  2. PHP's gettext extension looks for the locale on the system
  3. If the locale is not installed, gettext silently falls back to English
  4. Translation files (.mo files) are only loaded if the system locale exists

Important: Simply having translation files (.po and .mo) in ChurchCRM is not enough. The system must have the locale enabled.

How to Check If Locales Are Installed

On Linux (Debian/Ubuntu)

# List all installed locales
locale -a

# Check if a specific locale is installed (e.g., Spanish)
locale -a | grep es_ES

On Linux (Rocky Linux/RHEL/CentOS)

# List all installed locales
localectl list-locales

# Check if a specific locale is installed (e.g., Spanish)
localectl list-locales | grep es_ES

Common Locale Naming

ChurchCRM uses standard locale codes in the format language_COUNTRY:

  • Spanish: es_ES
  • French: fr_FR
  • German: de_DE
  • Portuguese (Brazil): pt_BR
  • Chinese (Simplified): zh_CN
  • Japanese: ja_JP
  • Russian: ru_RU

For a complete list of supported locales, see src/locale/locales.json in the ChurchCRM codebase.

How to Install Locales

On Debian/Ubuntu Systems

Use the locale-gen command to generate and install locales:

# Install a specific locale (e.g., Spanish)
sudo locale-gen es_ES.UTF-8

# Install multiple locales
sudo locale-gen es_ES.UTF-8
sudo locale-gen fr_FR.UTF-8
sudo locale-gen de_DE.UTF-8
sudo locale-gen pt_BR.UTF-8

# Update the locale cache
sudo update-locale

Alternative Method (Debian/Ubuntu):

# Edit the locale configuration file
sudo nano /etc/locale.gen

# Uncomment the locales you need (e.g., es_ES.UTF-8 UTF-8)
# Save and exit

# Generate the uncommented locales
sudo locale-gen

On Rocky Linux/RHEL/CentOS Systems

# Install the language pack (e.g., Spanish)
sudo dnf install glibc-langpack-es

# Install multiple language packs
sudo dnf install glibc-langpack-es glibc-langpack-fr glibc-langpack-de

# Set system locale if needed
sudo localectl set-locale LANG=es_ES.UTF-8

On macOS (for Development)

macOS typically has most locales pre-installed. To verify:

# List available locales
locale -a

# Most locales should be available by default

Common Language Packs by Distribution

Ubuntu/Debian:

sudo locale-gen es_ES.UTF-8      # Spanish
sudo locale-gen fr_FR.UTF-8      # French
sudo locale-gen de_DE.UTF-8      # German
sudo locale-gen pt_BR.UTF-8      # Portuguese (Brazil)
sudo locale-gen zh_CN.UTF-8      # Chinese (Simplified)
sudo locale-gen ja_JP.UTF-8      # Japanese
sudo locale-gen ru_RU.UTF-8      # Russian
sudo locale-gen ar_SA.UTF-8      # Arabic
sudo locale-gen hi_IN.UTF-8      # Hindi

Rocky Linux/RHEL/CentOS:

sudo dnf install glibc-langpack-es    # Spanish
sudo dnf install glibc-langpack-fr    # French
sudo dnf install glibc-langpack-de    # German
sudo dnf install glibc-langpack-pt    # Portuguese
sudo dnf install glibc-langpack-zh    # Chinese
sudo dnf install glibc-langpack-ja    # Japanese
sudo dnf install glibc-langpack-ru    # Russian
sudo dnf install glibc-langpack-ar    # Arabic
sudo dnf install glibc-langpack-hi    # Hindi

Enabling Localization in ChurchCRM

After installing the required system locales:

  1. Log in to ChurchCRM as an administrator
  2. Navigate to Admin → Edit General Settings
  3. Click the Settings tab
  4. Select System Settings
  5. Click the Localization tab
  6. Change sLanguage to your desired language from the dropdown
  7. Click Save Changes

ChurchCRM will now use the selected language for the user interface.

Troubleshooting

Translations Not Appearing

If you've selected a language but the interface still appears in English:

  1. Verify the system locale is installed:

    locale -a | grep <your_locale>

  2. Install the missing locale using the commands above

  3. Restart the web server after installing locales:

    # Apache
sudo systemctl restart apache2
# or
sudo systemctl restart httpd

# nginx + PHP-FPM
sudo systemctl restart php-fpm
sudo systemctl restart nginx

  4. Clear browser cache and reload ChurchCRM

  5. Check ChurchCRM logs in Admin → System Logs for locale-related errors

Verify PHP Gettext Extension

Ensure the gettext PHP extension is installed:

# Check if gettext is enabled
php -m | grep gettext

# Install if missing (Ubuntu/Debian)
sudo apt-get install php-gettext

# Install if missing (Rocky Linux/RHEL)
sudo dnf install php-gettext

# Restart web server after installation
sudo systemctl restart apache2

Check Translation Files

Verify that ChurchCRM has the compiled translation files:

# From ChurchCRM root directory
find src/locale/textdomain -name "*.mo"

# Should show files like:
# src/locale/textdomain/es_ES/LC_MESSAGES/messages.mo
# src/locale/textdomain/fr_FR/LC_MESSAGES/messages.mo

If .mo files are missing, run the locale download command (requires development environment):

npm run locale:download

Best Practices

For Production Servers

  1. Install all locales you plan to support when setting up the server
  2. Use UTF-8 encoding for all locales (e.g., es_ES.UTF-8 not es_ES)
  3. Restart the web server after installing new locales
  4. Test each language after enabling it in ChurchCRM
  5. Monitor logs for locale-related warnings

For Shared Hosting

If you're on shared hosting (cPanel, Plesk, etc.):

  1. Contact your hosting provider to request locale installation
  2. Most providers have common locales (es_ES, fr_FR, de_DE) pre-installed
  3. Verify available locales with your hosting support
  4. If locales cannot be installed, choose hosting that supports your required languages

For Docker/Container Deployments

In your Dockerfile, install required locales. ChurchCRM's setup wizard will detect which locales are available on the system:

# Debian/Ubuntu base - Install specific locales
RUN apt-get update && apt-get install -y locales && \
    locale-gen es_ES.UTF-8 && \
    locale-gen fr_FR.UTF-8 && \
    locale-gen de_DE.UTF-8 && \
    locale-gen pt_BR.UTF-8 && \
    locale-gen zh_CN.UTF-8 && \
    update-locale

# Or install all locales (larger image size)
RUN apt-get update && apt-get install -y locales-all

Note: ChurchCRM automatically detects available system locales during setup and shows their availability status. The setup wizard runs locale -a or uses setlocale() to check which locales are installed.

Common Locale Issues

Issue: "Locale Not Supported" Error

Symptom: PHP error like "locale 'es_ES' not supported by C library"

Solution: Install the locale on the system using locale-gen or dnf install glibc-langpack-*

Issue: Translations Work on Development but Not Production

Symptom: Translations work locally but fail on production server

Solution: Production server likely missing the locale. Install it using the commands for your distribution above.

Issue: Some Strings Translated, Others Not

Symptom: Partial translations appear

Possible Causes:

  1. Translation file incomplete (check POEditor translation progress)
  2. Some strings not yet extracted for translation
  3. Cache issue (clear browser cache)

Solution: Run npm run locale:audit to check translation completeness

Additional Resources

See Also

Website - Demo System (Latest Stable Release) - Twitter @church_crm

🚀 Getting Started

👥 Using ChurchCRM

🔧 System Administration

👨‍💻 For Developers

📚 Reference

Clone this wiki locally