l10n-audit-toolkit 1.2.1

Cross-framework localization audit and translation QA toolkit

L10n Audit Toolkit

L10n Audit Toolkit is a Python-based localization QA toolkit for auditing translation files, validating runtime-sensitive strings, and producing safe localization review workflows for multilingual applications.

📚 Documentation: 👉 https://wael-daaboul.github.io/L10n-Audit-Toolkit/

🇸🇦 الدليل العربي: للاطلاع على دليل الأوامر باللغة العربية، راجع USAGE_AR.md.

pipx install l10n-audit-toolkit

Overview

L10n Audit Toolkit helps engineering and localization teams catch issues before translations ship to production. It combines code usage scanning, locale-file validation, placeholder validation, terminology audit, glossary enforcement, and translation QA reporting in a single repository-oriented workflow.

The project is designed for teams that need repeatable localization audits for i18n and l10n pipelines without rewriting their application structure. It supports JSON locale files and Laravel PHP translation files, generates machine-readable and spreadsheet reports, and keeps risky changes in a review queue instead of auto-applying them.

Problem It Solves

Modern multilingual applications often fail in production because translation QA is fragmented across manual review, ad hoc scripts, and framework-specific checks. Common issues include:

• missing or unused translation keys
• placeholder mismatch detection failures
• glossary drift and terminology inconsistency
• ICU message mistakes
• unsafe formatting cleanup
• review workflows that are hard to trace or apply safely

L10n Audit Toolkit addresses those problems with a structured localization audit pipeline and explicit safe-fix boundaries.

Key Features

• Localization audit workflow for repository-based translation QA
• Static translation usage scanning across supported frameworks
• Placeholder validation for common runtime interpolation styles
• Terminology audit and glossary enforcement
• English and Arabic locale quality checks
• ICU message validation
• Safe localization fixes with a review-required path for risky changes
• Review queue generation in XLSX for human approval
• Final locale export in the original supported format
• JSON, CSV, XLSX, and Markdown outputs for CI or manual review

Supported Frameworks and Formats

Built-in project profiles currently cover:

• Flutter with GetX JSON localization
• Laravel JSON localization
• Laravel PHP localization
• React with i18next JSON
• Vue with vue-i18n JSON

Current locale format support:

• JSON locale files
• Laravel PHP translation files that use static parseable return arrays such as return [...] and return array(...)

What The Toolkit Detects

The toolkit can report issues such as:

• missing translations
• unused keys
• placeholder mismatch detection problems
• renamed or reordered placeholders
• terminology violations
• glossary enforcement failures
• ICU syntax and branch mismatches
• English locale wording and grammar issues
• Arabic locale spacing, punctuation, and context-sensitive review findings
• Arabic semantic review suggestions for sentence-level meaning loss
• risky review items that require explicit human approval

🚀 Quick Start

The L10n Audit Toolkit now comes with a powerful CLI. To get started in your localization project:

1. Initialize Workspace:

   l10n-audit init
   

2. Verify Setup:

   l10n-audit doctor
   

3. Run a Fast Audit:

   l10n-audit run --stage fast
   

Primary outputs are written under Results/.

💻 CLI Commands

Here are the main commands you will use daily:

• l10n-audit --help - Shows help, usage instructions, and available arguments.
• l10n-audit --version - Displays the current installed version of the toolkit.
• l10n-audit init - Discovers your project and creates the .l10n-audit/ workspace.
• l10n-audit run --stage <STAGE> - Runs specific or all audit modules (e.g., fast, full, autofix).
• l10n-audit update - Fetches the latest global rules and dictionaries to your local workspace.
• l10n-audit self-update - Guidance for upgrading your toolkit installation via pipx.

🌐 Local HTTP API (Non-blocking)

The L10n Audit Toolkit now includes a local FastAPI server (v1.2.1) for integration with web dashboards. The API is non-blocking and handles long-running audits gracefully using a background threadpool.

🐍 Python API

The L10n Audit Toolkit now offers an official Python API for integration into web platforms and CI scripts:

from l10n_audit import init_workspace, run_audit

# Initialize a new workspace
init_workspace("/path/to/project", force=False)

# Run an audit stage
result = run_audit("/path/to/project", stage="fast")

print(f"Audit Result: {result.summary.total_issues} issues found.")
for report in result.reports:
    print(f"Generated report: {report.name} at {report.path}")

🤖 AI-Powered Review

You can enhance your audits with AI (e.g., OpenAI, OpenRouter) to check context, tone, and grammar:

l10n-audit run --stage ai-review \
  --ai-enabled \
  --ai-api-base "https://openrouter.ai/api/v1" \
  --ai-model "openai/gpt-4o-mini"

🌐 Local HTTP API (New in v1.2.1)

The toolkit now includes a reference FastAPI implementation for integration with other tools:

cd http_api
pip install -r requirements.txt
uvicorn server:app --reload

Then visit http://localhost:8000/docs to see the automated Swagger documentation.

Note: For deep technical details and developer scripts, check the docs/ folder.

If you are using the repository checkout directly rather than an installed launcher, you can still run:

./bin/run_all_audits.sh --stage fast

Installation

Use the bootstrap script for the fastest setup:

./bootstrap.sh

Manual setup:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -r requirements-optional.txt
python -m pip install -r requirements-dev.txt

Detailed environment setup is documented in INSTALL.md and docs/quickstart.md.

The repository ships with a neutral example glossary at docs/terminology/glossary.json. Replace it or point glossary_file to your own JSON glossary.

Running Audits

Run the full localization audit pipeline:

l10n-audit run --stage full

Useful stage-specific commands:

l10n-audit run --stage ai-review --ai-enabled
l10n-audit run --stage ai-review --ai-enabled --ai-model gpt-4o-mini --ai-api-base https://api.openai.com/v1
l10n-audit doctor
l10n-audit update --check

To refresh local workspace templates from GitHub or a direct archive URL:

l10n-audit init --from-github --channel stable --repo https://github.com/your-org/l10n-audit-toolkit
l10n-audit update --from-github --channel main --repo https://github.com/your-org/l10n-audit-toolkit

You can also pass a direct .zip archive URL or file://...zip path during testing.

You can also run the basic localization usage audit directly:

./bin/l10n_audit.sh

Safe Fixes and Review Workflow

The toolkit separates deterministic changes from human-reviewed changes.

1. Run audits and generate reports.
2. Review Results/final/final_audit_report.md.
3. Open Results/review/review_queue.xlsx.
4. Fill approved_new for reviewed rows and set status to approved.
5. Apply approved fixes with:

python -m fixes.apply_review_fixes

6. Use the final locale output from Results/final_locale/.

Safe auto-fix planning is available with:

./bin/run_all_audits.sh --stage autofix

The review and fix workflow is documented in HOW_TO_USE.md and docs/review_workflow.md.

Example CLI Usage

./bin/run_all_audits.sh --stage full
python -m audits.placeholder_audit
python -m audits.terminology_audit
python -m fixes.apply_safe_fixes
python -m fixes.apply_review_fixes
python -m pytest

Example Outputs

Common outputs include:

• Results/per_tool/: raw per-audit findings
• Results/normalized/: normalized machine-readable findings
• Results/review/review_queue.xlsx: review queue for human approval
• Results/fixes/fix_plan.json: safe fix plan
• Results/fixes/safe_fixes_applied_report.json: auto-fix summary
• Results/final/final_audit_report.md: aggregated dashboard
• Results/final_locale/ar.final.json: final reviewed locale

See docs/output_reports.md for report details.

Repository Structure

• audits/: audit modules for localization, placeholder, terminology, ICU, and locale QA checks
• core/: shared runtime, loaders, exporters, scanners, and validation helpers
• fixes/: safe-fix and reviewed-fix application logic
• reports/: report aggregation and final dashboard generation
• schemas/: JSON schemas for config and generated artifacts
• config/: toolkit configuration and project profiles
• bin/: shell entry points for common workflows
• examples/: framework-oriented sample layouts and usage notes
• docs/: reference documentation for workflows and outputs
• tests/: regression coverage for audits, exports, reports, and fix safety

Detailed directory roles are documented in docs/overview.md.

Documentation

• INSTALL.md: environment and dependency setup
• HOW_TO_USE.md: workflow-oriented usage guide
• docs/quickstart.md: shortest path to first successful run
• docs/audit_modules.md: audit module reference
• docs/review_workflow.md: fix plan and review queue behavior
• docs/ai_usage.md: AI-assisted translation review and CLI options
• docs/output_reports.md: generated outputs and report formats
• docs/configuration.md: detailed configuration schema and profiles
• docs/ci_cd_integration.md: GitHub Actions and GitLab CI setups
• docs/terminology_guide.md: formatting your custom glossary.json
• examples/README.md: supported example layouts

Contributing

Contributions that improve localization audit quality, translation validation, framework coverage, or documentation are welcome. See CONTRIBUTING.md before opening a pull request.

Security

Please report vulnerabilities privately. See SECURITY.md.

License

This repository is released under the MIT License. See LICENSE.