Remove locale:missing; standardise on locale:download:missing

.agents/skills/churchcrm/locale-ai-translation.md

@@ -18,7 +18,7 @@ No API key or external service is required — translations run directly inside
 
 Every new UI string added to ChurchCRM creates a translation gap in 45+ languages. The AI translation system bridges that gap at release time by:
 
-1. Reading empty batch files from `locale/terms/missing/{locale}/*.json` (generated by `npm run locale:missing`)
+1. Reading empty batch files from `locale/terms/missing/{locale}/*.json` (generated by `npm run locale:download:missing`)
 2. Translating missing values with Claude Code, applying denomination-aware church vocabulary
 3. Writing translated values back into the same batch files
 4. User uploads those files to POEditor (source of truth), then pulls down via `npm run locale:download`
@@ -33,8 +33,8 @@ Every new UI string added to ChurchCRM creates a translation gap in 45+ language
 ## Quick Start
 
 ```bash
-# 1. Regenerate missing terms list
-npm run locale:missing
+# 1. Download untranslated terms from POEditor
+npm run locale:download:missing
 
 # 2. Preview what needs translation
 npm run locale:translate:list
@@ -67,7 +67,7 @@ npm run locale:download
 
 | Script | What it does |
 |--------|-------------|
-| `npm run locale:missing` | Regenerate missing-terms batch files |
+| `npm run locale:download:missing` | Download untranslated terms per locale from POEditor |
 | `npm run locale:translate:list` | List locales with untranslated terms |
 | `npm run locale:audit` | Show translation coverage report |
 | `npm run locale:download` | Pull approved translations from POEditor |

.claude/commands/locale-release.md

@@ -4,13 +4,13 @@ Run the full localization pipeline before a release: regenerate missing terms, t
 
 ## Steps
 
-### Step 1 — Regenerate missing terms
+### Step 1 — Download missing terms from POEditor
 
 ```bash
-npm run locale:missing
+npm run locale:download:missing
 ```
 
-This compares `locale/messages.json` against all installed `src/locale/i18n/*.json` files and writes fresh empty batch files to `locale/terms/missing/{locale}/`.
+This queries POEditor with `filters=untranslated` for each locale and writes fresh empty batch files to `locale/terms/missing/{locale}/`.
 
 ### Step 2 — Preview what needs translation
 

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

@@ -224,22 +224,22 @@ jobs:
         git config user.name "github-actions[bot]"
         git config user.email "github-actions[bot]@users.noreply.github.com"
 
-    - name: Generate missing terms for all locales
+    - name: Download missing terms for all locales from POEditor
       if: inputs.operation_mode != 'audit-only'
       run: |
-        echo "📋 Generating missing translation terms for all locales..."
-        npm run locale:missing
-        echo "✅ Missing terms files generated"
+        echo "📋 Downloading missing translation terms for all locales from POEditor..."
+        npm run locale:download:missing
+        echo "✅ Missing terms files downloaded"
 
     - name: Commit missing terms for POEditor
       if: inputs.operation_mode != 'audit-only'
       run: |
-        if [ -d "locale/missing-terms" ] && [ -n "$(find locale/missing-terms -name 'poeditor-*.json' -type f 2>/dev/null)" ]; then
+        if [ -d "locale/terms/missing" ] && [ -n "$(find locale/terms/missing -name '*.json' -type f 2>/dev/null)" ]; then
           echo "📝 Committing missing terms files..."
-          git add locale/missing-terms/poeditor-*.json
+          git add locale/terms/missing/
           # Check if there are staged changes to commit
           if ! git diff --cached --quiet; then
-            git commit -m "📊 Missing translation terms: Updated for all locales from master list"
+            git commit -m "locale: update missing translation terms from POEditor"
             echo "✅ Missing terms files committed"
           else
             echo "ℹ️  No new missing terms to commit"
@@ -278,11 +278,11 @@ jobs:
           **What's included:**
           - Updated translation files from POEditor
           - Generated locale JSON files
-          - 📊 Missing terms for all locales (in `locale/missing-terms/poeditor-*.json`)
+          - 📊 Missing terms for all locales (in `locale/terms/missing/`)
           - Locale audit results
 
           **Missing Terms Reports:**
-          For each incomplete locale, a `poeditor-{locale}.json` file contains all missing/untranslated terms from the master English list. These can be imported into POEditor to help translators complete the translations.
+          For each incomplete locale, batch files under `locale/terms/missing/{locale}/` contain all untranslated terms downloaded directly from POEditor. These can be used with `/locale-translate` or uploaded directly to POEditor.
 
           This PR was automatically created by the POEditor workflow.
 

locale/README.md

@@ -24,6 +24,7 @@ locale/
 ### Locale Management
 - `npm run locale:audit` - Generate locale completeness report
 - `npm run locale:download` - Download latest translations from POEditor
+- `npm run locale:download:missing` - Download **only untranslated (missing) terms** per locale from POEditor
 - `npm run locale:term-extract` - Extract all translatable terms for POEditor upload
 
 ### Manual Scripts (require parameters)
@@ -63,33 +64,27 @@ ChurchCRM uses [POEditor](https://poeditor.com) as the primary translation manag
 
 ### Missing Terms Workflow
 
-For identifying and prioritizing untranslated terms:
+Uses POEditor's `filters=untranslated` export filter to download only the missing terms
+directly from the API — no prior `locale:download` needed.
 
-1. **Generate Missing Terms**: `npm run locale:missing`
-   - Compares POEditor terms against each locale's translated terms
-   - Creates JSON files in `locale/terms/missing/{locale}/`
-   - Files are batched (default 150 terms per file) for easy POEditor import
-
-2. **Upload to POEditor**: 
-   - Go to POEditor → Your Project → Import
-   - Select language and upload the JSON files from `locale/terms/missing/{locale}/`
-   - POEditor will highlight these as needing translation
+```bash
+npm run locale:download:missing              # All locales
+npm run locale:download:missing -- --locale fr  # French only
+```
 
-3. **Translation Priority**:
-   - Files are named `{locale}-1.json`, `{locale}-2.json`, etc.
-   - Lower numbers = higher priority (most common terms)
-   - Translators should complete batch 1 before moving to batch 2
+Output: `locale/terms/missing/{poEditorCode}/{code}-N.json`
 
-4. **Download Updates**: After translators complete work, run `npm run locale:download`
+Batch files contain at most 150 terms each. Locales with fewer than 10 missing terms are
+skipped automatically. Files are ready for `/locale-translate` or direct upload to POEditor.
 
 ### Quick Reference Commands
 
 ```bash
 # Full translation workflow
-npm run locale:build      # Extract all terms from source code
-npm run locale:download   # Download translations from POEditor
-npm run locale:audit      # Generate completeness report
-npm run locale:missing    # Generate missing term files for each locale
+npm run locale:build                         # Extract all terms from source code
+npm run locale:download                      # Download translations from POEditor
+npm run locale:audit                         # Generate completeness report
+npm run locale:download:missing              # Fetch untranslated terms from POEditor
 ```
 
 ## 📝 Gettext System

locale/scripts/locale-translate.js

@@ -86,7 +86,7 @@ function countUntranslated(terms) {
 function cmdList(localeMap) {
     const missingDir = config.terms.missing;
     if (!fs.existsSync(missingDir)) {
-        console.log('No missing terms directory found. Run: npm run locale:missing');
+        console.log('No missing terms directory found. Run: npm run locale:download:missing');
         return;
     }