L10n-Audit-Toolkit

L10n Audit Toolkit

Automated localization auditing, validation, and repair — built for real-world production pipelines.

🚀 What’s New in v1.7.1

Canonical source guard enabled by default for deterministic source-identity enforcement.
Safer AI invocation with stricter semantic validation and reduced false-positive suggestions.
Deterministic AI review outcome handling — results are reproducible across runs.
Improved review/apply safety alignment with explicit frozen-artifact enforcement.
AI provider resilience: bounded exponential backoff and rate-limit-aware circuit breaker.
Cleaner CLI output: truthful final summaries with AI status and export status surfaced.
LiteLLM stdout/stderr noise contained in normal mode; full output preserved in debug mode.
Semantic precision improvements for short strings and domain-sensitive UI labels.

See CHANGELOG.md for full history including v1.7.0.

💡 Why This Tool Is Different

No split-brain after apply
Deterministic reconciliation
Designed for production workflows
Master-first architecture

🛑 What Problem It Solves

Localization often breaks in subtle ways that automated tests miss and human reviewers overlook:

Inconsistent terminology across hundreds of keys.
Broken placeholders (e.g., UI variables lost in translation).
Mixed-script errors (e.g., hidden English characters in Arabic text).
“Good enough” translations that miss the semantic context.

L10n Audit Toolkit provides a deterministic, repeatable, and automated pipeline to catch these issues before they reach production. It acts as a safety net between translators language files and your codebase.

✨ Key Features

🔍 Multi-stage audit pipeline: Fast rules-based checks, full ICU validation, and optional AI-driven semantic review.
🧠 AI-assisted review (optional): Intelligently analyzes context to suggest culturally and semantically accurate translations.
🔁 Reconciliation-safe apply system: Safely merges approved human and machine fixes back into your original files.
📦 Centralized audit master: A single source of truth (audit_master.json) for the entire pipeline state.
⚙️ CLI-first workflow: Designed for CI/CD integration with structured, deterministic outputs.

🚀 Quickstart

# 1. Initialize your workspace (detects framework, sets up .l10n-audit/)
l10n-audit init

# 2. Run the audit pipeline against your locale files
l10n-audit run

# 3. Freeze approved rows into an execution-safe workbook
l10n-audit prepare-apply

# 4. Apply reviewed fixes back to your codebase
l10n-audit apply

Primary review/apply workflow:

run -> review_queue.xlsx -> prepare-apply -> review_final.xlsx -> apply

Adaptive config workflow:

generate-adaptation-report -> generate-manifest -> review-manifest -> apply-manifest

This generates:

Results/final/final_audit_report.json
Results/review/review_queue.xlsx
Results/review/review_final.xlsx
Results/artifacts/audit_master.json

📊 Output Overview

The toolkit generates a structured set of outputs to guide both humans and machines:

Results/artifacts/audit_master.json → The core application state and single source of truth.
Results/review/review_queue.xlsx → The editable human review workspace.
Results/review/review_final.xlsx → The frozen, execution-safe contract generated by prepare-apply. Do not edit this file manually.
Results/final/final_audit_report.md → The dashboard-style Markdown summary of your localization health.

File	Role
`review_queue.xlsx`	Editable human review workspace
`review_final.xlsx`	Frozen execution contract

⚠️ Note:

Per-tool CSV/XLSX outputs are optional and disabled by default to reduce noise.

The .cache/ directory contains internal, raw processing data and should be ignored by version control.

🏗️ Architecture (High-Level)

The toolkit operates on a unidirectional, safe pipeline:

Audit: Reads project locales and runs heuristics/AI to detect issues.
Aggregate: Merges all findings into audit_master.json.
Review: Projects the master state into the editable human workspace review_queue.xlsx.
Prepare Apply: Transforms the editable review workspace into review_final.xlsx, a deterministic, execution-safe workbook.
Apply: Reads only review_final.xlsx and applies approved fixes to temporary .fix files.
Reconcile: Merges the application results back into the master state for a complete audit trail.

For explicit adaptive configuration changes, the toolkit uses a separate manual chain:

Generate Adaptation Report: Builds adaptation_report.json from a learning profile.
Generate Manifest: Converts the adaptation report into a reviewable consumption manifest.
Review Manifest: Produces a reviewed manifest with explicit human approvals.
Apply Manifest: Applies only approved manifest actions to config.json.

👥 Who Should Use This

Localization Teams: Ensure comprehensive terminology consistency without manual grepping.
Developers: Catch broken placeholders or formatting variables before deployment.
QA Teams: Automate multi-language validation within CI/CD pipelines to guarantee UI integrity.

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

🧠 Decision Quality Layer

The toolkit now includes a production-ready Decision Quality layer that is:

measurable
explainable
deterministic

Decision quality output is machine-readable and built around these stable metrics:

route_distribution → distribution of final decision routes
confidence_bands → distribution of high / medium / low confidence findings
evidence_source_usage → how often each evidence source influenced decisions
contribution_impact_summary → aggregated bonus/penalty impact by source
quality_risk_indicators → analytical warning signals such as low-confidence auto-fix cases, high-confidence manual cases, explanation gaps, and evidence-heavy caution patterns

This layer measures decision behavior without changing decision behavior. It is kept separate from routing and scoring execution so the system remains auditable and deterministic.

This site is open source. Improve this page.