Localization For Developers

Localization Guide for Developers

This page is for developers who want to manage, extend, or troubleshoot ChurchCRM's localization system.

Overview

• Technical details for integrating, extracting, and deploying translations
• Script usage, configuration, and troubleshooting
• Adding new locales to the system and POEditor

Locale Management Scripts

• npm run locale:build — Extracts all translatable terms from code, database, and static data into messages.po and builds locale files
• npm run locale:download — Downloads latest translations from POEditor and updates local files
• npm run locale:audit — Generates a completeness report (see CRM/locale/poeditor-audit.md)
• npm run locale:missing — Generates JSON batch files of missing terms for each locale (used for AI/translator workflows)
• npm run locale:variants — Populates variant locale files based on base locales
• npm run locale:lint — Checks for locale file issues and consistency

Note: The GitHub Action automatically runs locale:download and locale:missing on a regular cycle to keep translations and missing-term batches up to date.

How to Add a New Locale

• Add the new locale to src/locale/locales.json with the correct language code and metadata.
• Create the directory structure: mkdir -p src/locale/textdomain/<locale>/LC_MESSAGES
• Run npm run locale:build to generate the initial messages.po.
• Upload the new messages.po to POEditor and add the language in the POEditor project if not already present.
• Download translations with npm run locale:download after terms are translated.
• For full technical details, see the CRM/locale/README.md file in the codebase (not in the wiki).

Troubleshooting & Reference

• See the CRM/locale/README.md file in the codebase for all technical details, scripts, troubleshooting, and configuration (not in the wiki)
• See the Locale Audit Report for up-to-date translation status and completeness