https://github.com/tryggvigy/pseudo-localization
Dynamic pseudo-localization in the browser and nodejs
https://github.com/tryggvigy/pseudo-localization
bidi chaos-engineering i18n internationalization l10n language localization pseudo pseudo-localization pseudo-localize translation
Last synced: 23 days ago
JSON representation
Dynamic pseudo-localization in the browser and nodejs
- Host: GitHub
- URL: https://github.com/tryggvigy/pseudo-localization
- Owner: tryggvigy
- License: mit
- Created: 2018-08-06T23:31:16.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-02T19:27:47.000Z (about 2 years ago)
- Last Synced: 2024-07-03T18:02:10.633Z (10 months ago)
- Topics: bidi, chaos-engineering, i18n, internationalization, l10n, language, localization, pseudo, pseudo-localization, pseudo-localize, translation
- Language: HTML
- Homepage: https://tryggvigy.github.io/pseudo-localization/hamlet.html
- Size: 1.31 MB
- Stars: 141
- Watchers: 4
- Forks: 16
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome - pseudo-localization - Dynamic pseudo-localization in the browser and nodejs (HTML)
- awesome-web - Pseudo localization
README
Inspired by pseudo-localization at [Netflix](https://medium.com/netflix-techblog/pseudo-localization-netflix-12fff76fbcbe) and [Firefox](https://reviewboard.mozilla.org/r/248606/diff/2#index_header).
# Pseudo-Localization
Pseudo-localization helps developers test UI elements for localization issues before actual translations are available. This package transforms text into a pseudo-language to simulate real-world localization challenges.
## Preview
| English | Pseudo Language |
| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
### [Live Demo](https://tryggvigy.github.io/pseudo-localization/hamlet.html)
See it in action on [https://tryggvigy.github.io/pseudo-localization/hamlet.html](https://tryggvigy.github.io/pseudo-localization/hamlet.html)
Changes to the DOM trigger pseudo-localization in real time. Try modifying text nodes or adding/removing elements via DevTools.
---
## Why Use This?
Pseudo-localization helps detect issues such as:
- **Text Overflow** – Translations are often longer than the original text, which may cause UI breaking.
- **Font Rendering** – Certain languages have larger glyphs or diacritics that may be cut off.
- **Right-to-Left (RTL) Support** – Ensures proper layout handling for RTL languages.
- **Hardcoded Strings** – Identifies untranslated or hardcoded text that should be localized.
---
## Installation
### Via npm
```sh
npm install pseudo-localization
```
### Copy The Source Code
Copy the files from [`src`](https://github.com/tryggvigy/pseudo-localization/blob/master/src) and use them directly.
---
## Usage
### `pseudoLocalizeString`
Transform individual strings:
```js
import { pseudoLocalizeString } from 'pseudo-localization';
console.log(pseudoLocalizeString('hello')); // ħḗḗŀŀǿǿ
console.log(pseudoLocalizeString('hello', { strategy: 'bidi' })); // oʅʅǝɥ
```
Use-case: Ensure text is passing through a translation function.
```js
import translate from './my-translation-lib';
const _ = (key) => pseudoLocalizeString(translate(key, navigator.language));
console.log(_('Some Localized Text')); // Şǿǿḿḗḗ Ŀǿǿƈȧȧŀīẑḗḗḓ Ŧḗḗẋŧ
```
---
### `pseudo-localization/dom`
Automatically localize the entire page or parts of the DOM.
#### React Example
```jsx
import React, { useEffect } from 'react';
import { PseudoLocalizeDom } from 'pseudo-localization/dom';
function Page() {
useEffect(() => PseudoLocalizeDom.start(), []);
return
This text will be pseudo-localized!
;
}
```
---
## Strategies
Pseudo-localization supports two strategies:
### 1. Accented (`accented`)
Expands text and replaces Latin letters with accented Unicode counterparts.
```js
pseudoLocalization.start({ strategy: 'accented' });
```
Example output: **Ȧȧƈƈḗḗƞŧḗḗḓ Ḗḗƞɠŀīīşħ**
---
### 2. Bidirectional (`bidi`)
Simulates an RTL language by reversing words and using right-to-left Unicode formatting.
```js
pseudoLocalization.start({ strategy: 'bidi' });
```
Example output: **ɥsıʅƃuƎ ıpıԐ**
---
## API Reference
### `pseudoLocalizeString(str: string, options?: Options): string`
- `str`: String to localize.
- `options.strategy`: `'accented'` (default) or `'bidi'`.
### `PseudoLocalizeDom.start(options?: DomOptions): StopFn`
Pseudo-localizes the page and watches for DOM changes.
```js
import { PseudoLocalizeDom } from 'pseudo-localization/dom';
const stop = new PseudoLocalizeDom().start();
// Stop pseudo-localization later
stop();
```
#### `DomOptions`
- `strategy`: `'accented'` or `'bidi'`.
- `blacklistedNodeNames`: Nodes to ignore (default: `['STYLE']`).
- `root`: Root element for localization (default: `document.body`).
---
## CLI Usage
A command-line interface (CLI) is available for quick testing and automation.
```sh
npx pseudo-localization "hello world"
```
### CLI Options
```
pseudo-localization [src] [options]
Positionals:
src Input string
Options:
--strategy Localization strategy (accented or bidi)
--help Show help
```
---
## Browser Compatibility
Works in all modern browsers.
---
By using pseudo-localization, you can catch UI issues early, ensuring your app is truly localization-ready!