i18n-radar: Engineering a Type-Safe i18n Audit Pipeline

In large-scale Frontend architectures—especially those requiring complex RTL/LTR support like Arabic-English platforms—internationalization (i18n) is often the weakest link in the CI/CD chain.

Throughout my 4 years of experience managing enterprise codebases, I identified a critical architectural gap: Translation integrity is predominantly left to runtime checks.

This reactive approach leads to production incidents caused by missing keys or critical parameter mismatches. While standard linters validate syntax, they fail to audit the logical consistency across hundreds of fragmented translation files distributed throughout a monorepo.

To address this engineering challenge, I architected i18n-radar, a format-agnostic static analysis tool designed to enforce i18n integrity at build-time.

The Technical Challenge: Distributed State & Parameter Safety

In modern architectures (Domain-Driven or Feature-Based), translation files are rarely centralized; they are co-located with components. Existing tooling failed to address:

1. Split-File Architectures: Inability to effectively map and validate thousands of fragmented .ts or .json files.
2. Lack of Parameter Type Safety: Failure to detect logic errors. For example, a {name} parameter existing in the "Base" language but being missing or mismatched (e.g., {user}) in the "Target" language.
3. AST Limitation: Inability to statically parse dynamic structures within TypeScript translation files.

The Solution: i18n-radar

My solution is a CLI tool that integrates into the CI/CD pipeline, establishing the "Base Language" structure as the immutable "Source of Truth".

Key Architectural Decisions:

• Runtime Compilation via Jiti: To support dynamic configurations, I integrated jiti for on-the-fly compilation of TypeScript and JavaScript files. This makes the tool completely agnostic to the underlying framework.
• High-Performance Globbing: Utilized optimized glob matching algorithms to handle complex, nested directory structures (e.g., src/**/{lang}.ts) prevalent in monorepos, ensuring scalability.
• Context-Aware Diffing Algorithm: Instead of simple string matching, I implemented a parsing logic that extracts and compares interpolation parameters. The tool provides semantic error reporting: "Expected parameter {name} in Target, but found {user} instead." This drastically reduces debugging time.
• Developer Experience (DX): Designed a collapsible "Tree View" reporter for the CLI to visualize hierarchical data in the terminal, ensuring clarity even when dealing with hundreds of errors.

Impact & ROI

Integrating i18n-radar into development workflow

• Elimination of i18n-related regression bugs in production.
• Automated Validation: Removing the need for manual translation checks during Code Reviews.
• Strict Type Safety: Ensuring logical parity across all supported languages regardless of the project scale.

The tool is open-sourced on NPM and is designed to drop into any modern TypeScript/JavaScript environment.

• 🔗 GitHub & Source Code: github.com/berkinduz/i18n-radar
• 🔗 npm Package: i18n-radar