chore: migrate BuildConfig to dotenv (#8112)

Replaces the legacy JSON-based BuildConfig system with modern dotenv
environment variable configuration.

> Re-submission of the BuildConfig portion from #8111, without the
Cypress reorganization changes.

### Changes
- Deleted `BuildConfig.json` and `BuildConfig.json.example`
- Created `.env.example` with minimal required variables (`DB_*`,
`POEDITOR_TOKEN`)
- Updated 3 locale scripts to use `require('dotenv').config()`
- Hardcoded POEditor project ID (77079) in scripts
- Simplified GitHub Actions workflow to pass `POEDITOR_TOKEN` as env var
only
- Added `dotenv` to devDependencies
- Updated `.gitignore` to exclude `.env` and `.env.local`
- Updated documentation in `locale/README.md` and `scripts/README.md`

### Migration for Developers
```bash
cp .env.example .env
# Add your POEDITOR_TOKEN value for locale:download and locale:audit tasks
# DB_* variables are optional — defaults work for both local and Docker
```

Author: DawoudIO

.env.example

@@ -0,0 +1,11 @@
+# Database Configuration for locale build scripts
+# Both local dev and Docker use the same defaults
+DB_HOST=localhost
+DB_PORT=3306
+DB_NAME=churchcrm
+DB_USER=churchcrm
+DB_PASSWORD=changeme
+
+# POEditor API Configuration for locale:download and locale:audit
+# Get your token from: https://poeditor.com/account/api
+POEDITOR_TOKEN=

.github/workflows/locale-poeditor-download.yml

@@ -90,15 +90,10 @@ jobs:
         fi
         echo "✅ POEditor token is configured"
 
-    - name: Create BuildConfig file
-      if: inputs.operation_mode != 'audit-only'
-      uses: jsdaniell/create-json@v1.2.3
-      with:
-        name: "BuildConfig.json"
-        json: '{"POEditor": { "id": "77079", "token": "${{ secrets.POEDITOR_TOKEN }}"}}'
-      
     - name: Download locales from POEditor
       if: inputs.operation_mode != 'audit-only'
+      env:
+        POEDITOR_TOKEN: ${{ secrets.POEDITOR_TOKEN }}
       run: |
         set -e  # Exit on any command failure
         echo "🌍 Downloading locales from POEditor..."

.gitignore

@@ -3,6 +3,10 @@
 .idea/
 .DS_Store
 
+# Environment variables (local and overrides)
+.env
+.env.local
+
 #Exclude folders
 vendor
 node_modules
@@ -24,7 +28,6 @@ src/skin/external
 
 # Configuration files with passwords
 src/Include/Config.php
-BuildConfig.json
 orm/propel.php
 
 # Perpl/Propel generated config

BuildConfig.json.example

@@ -35,18 +35,22 @@ ChurchCRM uses [POEditor](https://poeditor.com) as the primary translation manag
 
 ### Setup Requirements
 
-1. **POEditor Project Configuration**
-   - Project ID and API token must be configured in `BuildConfig.json`
-   - See `BuildConfig.json.example` for structure
-
-2. **BuildConfig.json Structure**
-   ```json
-   {
-     "POEditor": {
-       "id": "YOUR_PROJECT_ID",
-       "token": "YOUR_API_TOKEN"
-     }
-   }
+1. **Environment Configuration**
+   - Copy `.env.example` to `.env` (or `.env.local` for local-only overrides)
+   - Set `POEDITOR_TOKEN` from your POEditor API access (https://poeditor.com/account/api)
+   - Database credentials default to `localhost/churchcrm/changeme` (works for both local dev and Docker)
+
+2. **.env Configuration**
+   ```bash
+   # Database (optional - defaults shown)
+   DB_HOST=localhost
+   DB_PORT=3306
+   DB_NAME=churchcrm
+   DB_USER=churchcrm
+   DB_PASSWORD=changeme
+   
+   # POEditor (required for locale:download)
+   POEDITOR_TOKEN=your_api_token_here
    ```
 
 ### POEditor Workflow
@@ -232,9 +236,9 @@ The system generates several runtime files:
    - Verify Gettext files exist in `textdomain/`
 
 2. **POEditor Sync Failures**
-   - Verify `BuildConfig.json` has correct API credentials
+   - Verify `POEDITOR_TOKEN` is set in `.env` file
    - Check network connectivity to POEditor API
-   - Ensure project ID matches your POEditor project
+   - Ensure token has proper POEditor API permissions
 
 3. **Term Extraction Errors**
    - Ensure `xgettext` is installed on system

locale/README.md

@@ -14,6 +14,11 @@
  * - Saves comprehensive audit report to locale/poeditor-audit.md
  * - No external dependencies (uses Node.js built-ins)
  * 
+ * Requires environment variables:
+ * - POEDITOR_TOKEN (from POEditor API Access)
+ * 
+ * Note: POEditor project ID is hardcoded as 77079 (ChurchCRM official project)
+ * 
  * Output Files:
  * - Console: Formatted table output for immediate review
  * - src/locale/poeditor.json: Raw API response (for compatibility)
@@ -23,40 +28,29 @@
  * reports as they represent base locales rather than translation targets.
  */
 
+require('dotenv').config();
+
 const fs = require('fs');
 const path = require('path');
 const config = require('./locale-config');
 
 class LocaleAuditor {
     constructor() {
-        this.configPath = config.buildConfigJson;
-        this.configExamplePath = config.buildConfigExample;
         this.localesPath = config.localesJson;
         this.outputPath = config.poeditor.outputJson;
         this.reportPath = config.poeditor.auditReport;
-        this.config = null;
+        this.projectId = '77079'; // ChurchCRM POEditor project ID
+        this.apiToken = process.env.POEDITOR_TOKEN;
         this.locales = null;
     }
 
     /**
-     * Load configuration from BuildConfig.json or BuildConfig.json.example
+     * Load configuration from environment variables
      */
     loadConfig() {
         try {
-            let configFile = this.configPath;
-            if (!fs.existsSync(this.configPath)) {
-                if (fs.existsSync(this.configExamplePath)) {
-                    console.log('⚠️  BuildConfig.json not found, using BuildConfig.json.example');
-                    configFile = this.configExamplePath;
-                } else {
-                    throw new Error(`Configuration file not found: neither ${this.configPath} nor ${this.configExamplePath} exist`);
-                }
-            }
-            
-            this.config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-            
-            if (!this.config.POEditor || !this.config.POEditor.token || !this.config.POEditor.id) {
-                throw new Error('POEditor configuration missing in BuildConfig.json');
+            if (!this.apiToken) {
+                throw new Error('POEDITOR_TOKEN environment variable is required');
             }
 
             console.log('✅ Configuration loaded successfully');
@@ -93,8 +87,8 @@ class LocaleAuditor {
             console.log('🌍 Downloading language statistics from POEditor...');
 
             const formData = new URLSearchParams();
-            formData.append('api_token', this.config.POEditor.token);
-            formData.append('id', this.config.POEditor.id);
+            formData.append('api_token', this.apiToken);
+            formData.append('id', this.projectId);
 
             const response = await fetch('https://api.poeditor.com/v2/languages/list', {
                 method: 'POST',
@@ -278,7 +272,7 @@ class LocaleAuditor {
         markdown += `- Locales with 📝 **Monitor** (<5% completion) are tracked for future addition when they reach 5%\n`;
 
         markdown += `\n## Technical Notes\n\n`;
-        markdown += `- **Data Source:** POEditor API (Project ID: ${this.config.POEditor.id})\n`;
+        markdown += `- **Data Source:** POEditor API (Project ID: ${this.projectId})\n`;
         markdown += `- **Audit Script:** \`locale/locale-audit.js\`\n`;
         markdown += `- **Configuration:** \`src/locale/locales.json\`\n`;
         markdown += `- **Command:** \`npm run locale-audit\`\n\n`;

locale/scripts/locale-audit.js

@@ -13,9 +13,18 @@
  * - Generates PHP files with gettext() calls
  * - Handles countries and locales data
  * 
+ * Requires environment variables:
+ * - DB_HOST (default: localhost)
+ * - DB_PORT (default: 3306)
+ * - DB_NAME (default: churchcrm)
+ * - DB_USER (default: churchcrm)
+ * - DB_PASSWORD (default: changeme)
+ * 
  * Output: Creates PHP files in db-strings/ directory for xgettext processing
  */
 
+require('dotenv').config();
+
 const fs = require('fs');
 const mysql = require('mysql2/promise');
 const path = require('path');
@@ -29,39 +38,29 @@ if (process.argv.includes('--temp-dir')) {
 
 class DatabaseTermExtractor {
     constructor() {
-        this.configPath = config.buildConfigJson;
-        this.configExamplePath = config.buildConfigExample;
         this.stringsDir = config.temp.dbStrings;
         this.stringFiles = [];
         this.connection = null;
     }
 
     /**
-     * Load database configuration from BuildConfig.json or BuildConfig.json.example
+     * Load database configuration from environment variables
      */
     loadConfig() {
         console.log('=====================================================');
         console.log('========== Building locale from DB started ==========');
         console.log('=====================================================\n');
 
-        let configFile = this.configPath;
-        if (!fs.existsSync(this.configPath)) {
-            if (fs.existsSync(this.configExamplePath)) {
-                console.log(`⚠️  BuildConfig.json not found, using BuildConfig.json.example\n`);
-                configFile = this.configExamplePath;
-            } else {
-                throw new Error(`ERROR: Neither ${this.configPath} nor ${this.configExamplePath} exist`);
-            }
-        }
-
-        const buildConfig = fs.readFileSync(configFile, 'utf8');
-        const config = JSON.parse(buildConfig);
-
-        if (!config.Env?.local?.database) {
-            throw new Error(`ERROR: The configuration file does not have local db env, check BuildConfig.json.example for schema`);
-        }
+        const dbConfig = {
+            server: process.env.DB_HOST || 'localhost',
+            port: process.env.DB_PORT || 3306,
+            database: process.env.DB_NAME || 'churchcrm',
+            user: process.env.DB_USER || 'churchcrm',
+            password: process.env.DB_PASSWORD || 'changeme'
+        };
 
-        return config.Env.local.database;
+        console.log(`📦 Using database: ${dbConfig.user}@${dbConfig.server}:${dbConfig.port}/${dbConfig.database}`);
+        return dbConfig;
     }
 
     /**

locale/scripts/locale-build-db.js

@@ -3,6 +3,9 @@
  * 
  * Centralized configuration for all locale build scripts to ensure
  * consistent paths and settings across the build system.
+ * 
+ * Configuration is now loaded via environment variables (.env file).
+ * See .env.example for required variables.
  */
 
 const path = require('path');
@@ -22,8 +25,6 @@ const LocaleConfig = {
     i18nDir: path.join(PROJECT_ROOT, 'src/locale/i18n'),
     localesDir: path.join(PROJECT_ROOT, 'locale/locales'),
 
-    buildConfigJson: path.join(PROJECT_ROOT, 'BuildConfig.json'),
-    buildConfigExample: path.join(PROJECT_ROOT, 'BuildConfig.json.example'),
     i18nextParserConfig: path.join(__dirname, 'i18next-parser.config.js'),
 
     temp: {

locale/scripts/locale-config.js

@@ -11,18 +11,20 @@
  *   npm run locale:download -- --locale fi                  # Download Finnish only
  * 
  * Requires:
- * - BuildConfig.json (or BuildConfig.json.example) with POEditor.id and POEditor.token
+ * - POEDITOR_TOKEN environment variable (from .env or POEditor API Access)
  * - No additional npm packages (uses native https module)
+ * 
+ * Note: POEditor project ID is hardcoded as 77079 (ChurchCRM official project)
  */
 
+require('dotenv').config();
+
 const fs = require('fs');
 const path = require('path');
 const https = require('https');
 const { URLSearchParams } = require('url');
 
 // Configuration
-const CONFIG_FILE = path.join(__dirname, '../../BuildConfig.json');
-const CONFIG_EXAMPLE_FILE = path.join(__dirname, '../../BuildConfig.json.example');
 const LOCALES_FILE = path.join(__dirname, '../../src/locale/locales.json');
 const JSON_OUTPUT_DIR = path.join(__dirname, '../../src/locale/i18n');
 const MASTER_LIST_DIR = path.join(__dirname, '../'); // /locale directory for master English list
@@ -38,29 +40,13 @@ const FILE_FORMATS = [
     { type: 'mo', dir: TEXTDOMAIN_OUTPUT_DIR, ext: 'mo', filename: (locale) => `${locale}/LC_MESSAGES/messages.mo` },
 ];
 
-// Load configuration
-let buildConfig;
-let configFile = CONFIG_FILE;
-try {
-    if (!fs.existsSync(CONFIG_FILE)) {
-        if (fs.existsSync(CONFIG_EXAMPLE_FILE)) {
-            console.log('⚠️  BuildConfig.json not found, using BuildConfig.json.example');
-            configFile = CONFIG_EXAMPLE_FILE;
-        } else {
-            throw new Error('Neither BuildConfig.json nor BuildConfig.json.example exist');
-        }
-    }
-    buildConfig = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-} catch (e) {
-    console.error(`❌ Error reading configuration: ${e.message}`);
-    process.exit(1);
-}
-
-const projectId = buildConfig?.POEditor?.id;
-const apiToken = buildConfig?.POEditor?.token;
+// Load configuration from environment
+const apiToken = process.env.POEDITOR_TOKEN;
+const projectId = '77079'; // ChurchCRM POEditor project ID
 
-if (!projectId || !apiToken) {
-    console.error('❌ Missing POEditor configuration in BuildConfig.json');
+if (!apiToken) {
+    console.error('❌ POEDITOR_TOKEN environment variable is required');
+    console.error('   Get your token from: https://poeditor.com/account/api');
     process.exit(1);
 }