Pseudo-localization for Automated i18n Testing

Source: Dev.to

What is Pseudo‑localization?

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

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:

• Layout breakages – Text expansion (German, Finnish, etc.) can be 30 %–40 % longer than English.
• Encoding issues – Accented characters expose UTF‑8 problems.
• Translatability – Hard‑coded strings remain unchanged and are easy to spot.
• Placeholder handling – Dynamic content like {{name}} must be preserved.
• Length limits – Define safe UI‑component limits for languages that need more space.

---

Automation Strategies for QA

1. 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.

---

2. Text Expansion Simulation

Automatically expand each string by ~30 %–40 % to mimic long languages. Wrap with visual markers for easy clipping detection.

Example: “Save” → ⟦Šàvēēēēē⟧

QA check: Use automated screenshot comparison to spot UI overflow, clipping, or misalignment.

---

3. 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.

---

4. 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.

---

5. 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 the 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 30 %–40 % longer translations.
• Accented Characters – Tests UTF‑8 encoding and font support.
• Visual Markers – Wraps strings with ⟦…⟧ to 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

# Global installation (CLI usage)
npm install -g pseudo-l10n

# As a development dependency
npm install --save-dev pseudo-l10n

---

Basic Usage

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

pseudo-l10n input.json output.json

Example Transformation

Input (en.json):

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

Output (pseudo-en.json):

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

---

Advanced Features

Custom Expansion

pseudo-l10n en.json pseudo-en.json --expansion=30

RTL Simulation

pseudo-l10n en.json pseudo-en.json --rtl

Example:

{
  "greeting": "⟦Ĥëļļõēēēēēē, !ēēēēē⟧"
}

Placeholder Formats

The package supports various placeholder syntaxes used by different i18n libraries:

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

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

# sprintf style
pseudo-l10n en.json pseudo-en.json --placeholder-format="%key%"

---

Summary

By integrating pseudo‑l10n into your development and CI/CD pipelines, you can automatically detect:

• Layout breakages caused by text expansion
• Encoding problems with non‑Latin characters
• Missing or malformed placeholders
• RTL‑specific UI issues

This proactive approach ensures a smoother localization process and a more robust, globally‑ready application. Happy testing!

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}}!ēēēēē⟧

---

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"
  }
}

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 }
);

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

---

Testing Strategy

1. Generate a pseudo‑locale during your build process.
2. Add the pseudo‑locale to your application (e.g., in the language selector).
3. Test your application with the pseudo‑locale enabled.
4. Review the UI 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

• Preserves placeholders, format, and structure — just like pseudo‑l10n protects during testing.
• Supports 165 languages with context‑aware AI translation.
• Handles plural forms, interpolation, and special characters automatically.
• Provides CI/CD integration via API, the npm package ai‑l10n, or the GitHub Action for automated localization.
• Offers a VS Code extension and a web UI for manual i18n translation.

---

Complete i18n Workflow

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

Thanks for reading!