Skip to content

Localization with AI

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

ChurchCRM Localization with AI: Workflow & Tools

This page is split for two audiences:

For People Who Want to Help Localize

How to Add a New Locale

  • If your language is missing in POEditor, contact a project admin or open a GitHub issue to request it.

  • Once the locale is added, you can begin translating terms for it in POEditor.

  • When enough terms are translated, the language can be enabled in the app (see developer steps below).

  • How to use AI for translation:

    • Use the missing-terms system to get batches of untranslated terms
    • Paste a batch (e.g., ja-1.json) into an AI chat (like Copilot Chat or ChatGPT) with the prompt: "Translate these terms to [language]. Return only the JSON with translations."
    • Review and copy the AI's output back into the file, or use an agent to apply the changes

  • Best practices:

    • Work in small batches (50–100 terms)
    • Start with easy/common terms (months, days, UI labels)
    • Review context for ambiguous terms
    • Use consistent translations for repeated UI terms

  • Track your progress:

For Developers

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:term-extract 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 details, see CRM/locale/README.md.

  • Reference:

This page documents the workflow, tools, and best practices for using AI to accelerate and improve ChurchCRM localization. It is designed for translators, developers, and contributors who want to leverage the missing-terms system and AI chat agents for efficient translation.

1. Overview

ChurchCRM supports 45+ languages. To keep translations up-to-date and high quality, we use a combination of:

  • POEditor (professional translation platform)
  • Automated scripts (for extracting, downloading, and auditing terms)
  • AI chat agents (for rapid, context-aware translation of missing terms)
  • The missing-terms directory (for batching and managing incomplete translations)

2. Key Tools & Scripts

  • locale:build: Extracts all translatable terms from the codebase.
  • locale:download [--locale]: Downloads translations from POEditor. Use --locale for a single language (much faster).
  • locale:missing: Generates JSON files in locale/missing-terms/ for each locale with missing or empty translations, split into manageable batches.
  • locale:audit: Checks for completeness and consistency across all locales.
  • locale/missing-terms/: Directory containing per-locale, per-batch JSON files of untranslated terms (e.g., ja-1.json, hi-2.json).

3. The missing-terms Workflow

  1. Generate missing-terms files

    • Run npm run locale:missing after updating source terms or downloading from POEditor.
    • This creates files like locale/missing-terms/ja-1.json, each containing a batch of untranslated terms for a locale.

  2. Feed batches to AI for translation

    • Open a batch file (e.g., ja-1.json).
    • Paste its contents into an AI chat (like GitHub Copilot Chat, ChatGPT, or similar) with a prompt:

      "Translate these terms to Japanese. Return only the JSON with translations."

    • Review and copy the AI's output back into the file, or use an agent to apply the changes directly.

  3. Repeat for all batches/locales

    • Work through each batch file for the target locale(s).
    • For large languages, prioritize easy/common terms first (months, days, UI labels).

  4. Merge and upload

    • Once all batches are translated, merge them into the main locale file (e.g., src/locale/ja_JP.json).
    • Optionally, upload to POEditor for professional review and further translation.

  5. Rebuild and audit

    • Run npm run locale:build and npm run locale:audit to ensure all terms are present and correct.

4. Best Practices for AI-Assisted Localization

  • Batch size: Keep each JSON batch small (50–100 terms) for best AI results.
  • Easy terms first: Start with months, days, directions, and simple UI terms—these are high-confidence and universal.
  • Review context: For complex or ambiguous terms, provide extra context or review AI output carefully.
  • Standardize: Use consistent translations for repeated UI terms (e.g., "View", "OK", "Yes", "No").
  • Document changes: Track which batches have been translated and merged.

5. Example AI Prompt

Translate these terms to Hindi. Return only the JSON with translations. [Paste contents of hi-1.json here]

6. Sharing & Collaboration

  • Share this workflow with translators and contributors.
  • Encourage use of the missing-terms system for any new or updated locale.
  • Use the wiki to track progress and share best practices.

7. Additional Resources

Last updated: December 2025

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

🚀 Getting Started

👥 Using ChurchCRM

🔧 System Administration

👨‍💻 For Developers

📚 Reference

Clone this wiki locally