DEV Community

Anton Antonov
Anton Antonov

Posted on • Originally published at l10n.dev

Pseudo-localization for Automated i18n Testing

#testing #qa #frontend #automation

Pseudo-localization is a powerful testing technique that transforms your source text into a fake language to identify internationalization (i18n) issues before actual translation begins. This guide shows you how to automate pseudo-localization testing using the pseudo-l10n npm package.

What is Pseudo-localization?

Pseudo-localization is the process of transforming your application’s source text into an altered, fake language that mimics how UI behaves after translation. It helps QA engineers and developers identify i18n issues early in the development cycle.

Example of using pseudo-localization

Example of using pseudo-localization to identify potential internationalization issues. The font and size are identical on both sides, but supporting other scripts often requires more space.

Why Pseudo-localization is Useful

Pseudo-localization helps you catch i18n issues early:

  • Exposes layout breakages caused by text expansion (German and Finnish are typically 30–40% longer than English).
  • Surfaces encoding issues by adding accented characters to test UTF-8 support.
  • Ensures all strings are translatable — hard-coded text remains unchanged and is easy to spot.
  • Reveals placeholder mishandling — dynamic content like {{name}} must be preserved.
  • Helps define translation length limits for UI components with space constraints.

Automation Strategies for QA

Here are proven strategies to automate i18n testing with pseudo-localization:

Accented & Non-Latin Characters

Replace Latin letters with accented forms or different scripts to test character encoding and font support.
Example: “Save” → “Šàvē”
QA check: Ensure all characters display correctly and nothing breaks due to encoding issues.

Text Expansion Simulation

Automatically expand each string by ~30–40% to mimic long languages like German or Finnish. Wrap with visual markers for easy clipping detection.
Example: “Save” → ⟦Šàvēēēēē⟧
QA check: Use automated screenshot comparison to spot UI overflow, clipping, or misalignment.

Placeholder Stress Testing

Replace interpolation variables (placeholders) with visible markers to verify they’re preserved during translation.
Example: “You have {{count}} items” → “You have items”
QA check: Run regression tests; fail if a marker is missing or incorrectly escaped (<COUNT>).

RTL Simulation

Wrap text in right-to-left (RTL) markers using Unicode control characters to simulate Arabic or Hebrew.
QA check: Verify alignment, text direction, and mirroring are correct for RTL languages.

CI/CD Integration

Add pseudo-localization to your automated test pipeline to catch i18n issues before they reach production.
QA check: Block deployment if tests detect missing translations, broken placeholders, or layout issues.

Automating with pseudo-l10n Package

The pseudo-l10n npm package automates pseudo-localization for your JSON translation files, making it easy to integrate i18n testing into your development workflow.

Key Features

  • Text Expansion: Simulates how translated text is often 30–40% longer than English.
  • Accented Characters: Tests UTF-8 encoding and font support with accented equivalents.
  • Visual Markers: Wraps strings with ⟦…⟧ markers to easily spot untranslated or truncated text.
  • Placeholder Handling: Preserves placeholders like {{name}}, {count}, %key%, etc.
  • RTL Simulation: Simulates Right-to-Left languages using Unicode control characters.

Installation

Install pseudo-l10n globally for command-line usage:

npm install -g pseudo-l10n
Enter fullscreen mode Exit fullscreen mode

Or add it as a development dependency:

npm install --save-dev pseudo-l10n
Enter fullscreen mode Exit fullscreen mode

Basic Usage

Transform your source translation file into a pseudo-localized version:

pseudo-l10n input.json output.json
Enter fullscreen mode Exit fullscreen mode

Example Transformation
Input (en.json):

{
  "welcome": "Welcome to our application",
  "greeting": "Hello, {{name}}!",
  "itemCount": "You have {{count}} items"
}
Enter fullscreen mode Exit fullscreen mode

Output (pseudo-en.json):

{
  "welcome": "⟦Ŵëļçõɱë ţõ õür àƥƥļïçàţïõñēēēēēēēēēēēēēēēēēē⟧",
  "greeting": "⟦Ĥëļļõēēēēēē, {{name}}!ēēēēē⟧",
  "itemCount": "⟦Ŷõü ĥàṽë {{count}} ïţëɱšēēēēēēēēēēēēēēēē⟧"
}
Enter fullscreen mode Exit fullscreen mode

Advanced Features

Custom Expansion

pseudo-l10n en.json pseudo-en.json --expansion=30
Enter fullscreen mode Exit fullscreen mode

RTL Simulation

Simulate right-to-left languages like Arabic or Hebrew:

pseudo-l10n en.json pseudo-en.json --replace-placeholders

# Input:  { "greeting": "Hello, {{name}}!" }
# Output: { "greeting": "⟦Ĥëļļõēēēēēē, <NAME>!ēēēēē⟧" }
Enter fullscreen mode Exit fullscreen mode

Support for Different Placeholder Formats
The package supports various placeholder formats used by different i18n libraries:

# For i18next (default)
pseudo-l10n en.json pseudo-en.json --placeholder-format="{{key}}"

# For Angular/React Intl
pseudo-l10n en.json pseudo-en.json --placeholder-format="{key}"

# For sprintf style
pseudo-l10n en.json pseudo-en.json --placeholder-format="%key%"
Enter fullscreen mode Exit fullscreen mode

Programmatic Usage

Use pseudo-l10n programmatically in your Node.js scripts or build process:

const { generatePseudoLocaleSync, pseudoLocalize } = require('pseudo-l10n');

// Generate a pseudo-localized JSON file
generatePseudoLocaleSync('en.json', 'pseudo-en.json', {
  expansion: 40,
  rtl: false
});
// Pseudo-localize a single string
const result = pseudoLocalize('Hello, {{name}}!');
console.log(result);
// Output: ⟦Ĥëļļõēēēēēēēēēēēēēē, {{name}}!ēēēēē⟧
Enter fullscreen mode Exit fullscreen mode

Integration into Your Workflow

npm Scripts
Add pseudo-localization generation to your package.json scripts:

{
  "scripts": {
    "pseudo": "pseudo-l10n src/locales/en.json src/locales/pseudo-en.json",
    "pseudo:rtl": "pseudo-l10n src/locales/en.json src/locales/pseudo-ar.json --rtl"
  }
}
Enter fullscreen mode Exit fullscreen mode

Build Process Integration
Generate pseudo-locales as part of your build process:

// build.js
const { generatePseudoLocaleSync } = require('pseudo-l10n');

// Generate pseudo-locales as part of build
generatePseudoLocaleSync(
  './src/locales/en.json',
  './src/locales/pseudo-en.json',
  { expansion: 40 }
);
generatePseudoLocaleSync(
  './src/locales/en.json',
  './src/locales/pseudo-ar.json',
  { rtl: true }
);
Enter fullscreen mode Exit fullscreen mode

CI/CD Pipeline Integration
Integrate pseudo-localization into your continuous integration pipeline:

# .github/workflows/test.yml
- name: Generate pseudo-locales
  run: |
    npm install -g pseudo-l10n
    pseudo-l10n src/locales/en.json src/locales/pseudo-en.json

- name: Run i18n tests
  run: npm run test:i18n
Enter fullscreen mode Exit fullscreen mode

Testing Strategy

  1. Generate pseudo-locale during your build process.
  2. Add pseudo-locale to your application (e.g., in the language selector).
  3. Test your application with pseudo-locale enabled.
  4. Review the application for common i18n issues.

What to Look For

  • Missing ⟦⟧ markers = untranslated strings (hard-coded text).
  • Cut-off markers = text truncation or UI overflow.
  • Broken layout = insufficient space for text expansion.
  • Garbled text = encoding issues or missing font support.
  • Wrong text direction = RTL problems (for RTL pseudo-locales).

Pseudo-localization is an essential testing technique that helps you catch internationalization issues before they reach production. By automating pseudo-localization testing with the pseudo-l10n package, you can ensure your application is truly ready for global audiences.

From Testing to Real Translation

Once you’ve validated your i18n implementation with pseudo-localization, it’s time to translate your application for real users. This is where AI-powered translation services like l10n.dev come in.

Why l10n.dev for Production Translation

After ensuring your app handles internationalization correctly with pseudo-localization, use l10n.dev for professional AI-powered translation:

Complete i18n Workflow

Test your i18n implementation with pseudo-l10n to catch issues early.
Fix any layout, encoding, or placeholder issues discovered during testing.
Translate i18n files using l10n.dev for production-ready translations.

Thanks for reading!

Top comments (0)