pseudolocale

Pseudolocale is a small, focused TypeScript library for pseudolocalizing strings — a technique for testing the internationalization-readiness of an application before real translations exist. It replaces the characters of a string with accented or diacritic-marked look-alikes, optionally pads the string to simulate the length expansion of languages like German, and wraps the result in bracket markers so truncated or improperly concatenated strings are easy to spot visually.

The library is idempotent: calling it twice on the same input always produces the same output, which makes pseudolocalized snapshots stable in tests and visual regression tools. It understands interpolation tokens (%token% by default, or any custom delimiter pair) and leaves them untouched so dynamic values aren’t mangled. A dedicated right-to-left mode wraps text in Unicode RLO/PDF marks and swaps in visually-flipped glyphs, letting teams catch bidi-related layout bugs (RTL locales like Arabic or Hebrew) without needing an actual RTL translation.

Beyond the importable pseudolocale() function, the package ships a CLI (pseudolocale) built on Commander that can pseudolocalize an ad-hoc string or walk a JSON file of translation keys and write out a fully pseudolocalized copy — useful for wiring into a build step so every PR gets a pseudolocalized locale bundle for QA to click through.

With over a million weekly downloads and a decade of history, it’s a small utility with an unusually large install base — most commonly pulled in as a dev dependency by i18n-heavy frontend and CLI tooling projects.

What You Get

• A single pseudolocale(str, options) function that deterministically maps each character to an accented equivalent, so re-running it on the same string always yields the same output
• Configurable prepend/append markers (default [!! / !!]) to visually flag where a string starts and ends, exposing truncation or bad concatenation
• Token-aware transformation: text inside %token%-style delimiters (or any custom delimiter pair) is left untouched so interpolated values stay intact
• String extension via the extend option to pad output by a percentage, simulating languages (like German) that run longer than English
• An override mode that replaces every character with a single repeated character, making genuinely unlocalized strings trivial to spot
• A rightToLeft mode that wraps output in Unicode RLO/PDF marks and flips glyphs, for testing RTL/bidi layout without a real RTL translation
• A bundled CLI (pseudolocale) that pseudolocalizes an inline string or an entire JSON translation file in one command, suitable for a build/CI step

Common Use Cases

• Generating a pseudolocalized build/locale bundle in CI so QA can visually catch untranslated or truncated strings before a real translation pass starts
• Adding a pseudolocale CLI step to a JSON-based i18n pipeline to convert en.json into a en-pseudo.json locale for manual QA
• Testing that UI layouts survive ~30% longer strings by using the extend option to simulate German/French text expansion
• Validating RTL layout and bidi rendering early using the rightToLeft option, without needing an Arabic/Hebrew translator on hand
• Snapshot-testing that all user-facing strings actually pass through the i18n layer, by asserting the pseudolocalized output rather than the raw string

Under The Hood

Architecture The library is a thin, single-purpose pipeline: str.ts exposes the default export, which merges caller options over defaultOptions, calls token.ts’s getTokens() to run a delimiter-aware regex over the input and locate interpolation spans, then walks the string chunk-by-chunk — untouched inside token spans, transformed outside them — via a local transformChunk() helper that consults the mapping tables in charactersMapping.ts. The result is finally passed through pad.ts’s pad() for percentage-based extension and wrapped in the prepend/append markers. The CLI (cli.ts → command.ts) is a separate, optional consumer of the same str.ts export built on Commander, so removing the CLI entirely would not affect the core library’s behavior — it’s a genuinely layered, single-responsibility design with no hidden coupling between the transform logic and the CLI presentation layer.

Tech Stack Written in TypeScript, built with tsdown into ESM-only output (dist/index.mjs, dist/cli.mjs) targeting Node.js 24+, with type declarations emitted alongside. The only runtime dependency is commander for CLI argument parsing; there are no other production dependencies. Tooling is modern and minimal: ESLint (flat config) with typescript-eslint, Prettier for formatting, and vitest with @vitest/coverage-v8 for testing — a lean, single-purpose toolchain appropriate for a package this small.

Code Quality Testing is thorough relative to the codebase’s size: str.test.ts and command.test.ts together cover the character mapping, token/delimiter handling (including custom and multi-character delimiters), padding/extension, override mode, and the RTL path, plus CLI behavior for inline strings and file-based JSON transforms. CI (ci.yml) runs Prettier checks, a TypeScript type-check pass, a package-lock drift check, and vitest run --coverage on every PR and push to main, and a separate release.yml publishes to npm via OIDC trusted publishing with provenance on tag push — a notably mature release pipeline for a project of this size. Naming is consistent and functions are small and single-purpose; there is no dedicated error-handling layer because the library’s surface area (pure string transforms) has little that can meaningfully fail beyond file I/O in the CLI, which is wrapped in try/catch with user-facing messages.

What Makes It Unique The library’s core idea — deterministic, idempotent pseudolocalization rather than randomized character substitution — is what most alternatives in this space get wrong; determinism is what makes pseudolocalized output usable in stable snapshot tests and repeatable QA passes rather than a one-off manual check. Its dedicated rightToLeft mode, which combines visually-flipped glyphs with real Unicode bidi control characters (RLO/PDF) rather than just reversing text, is a more faithful simulation of true RTL rendering bugs than most pseudolocalization tools attempt, while still keeping delimiter-marked tokens correctly un-reversed.