pseudo-localization 3.0.3 → 3.1.0

package/README.md

@@ -37,7 +37,7 @@ Pseudo-localization helps detect issues such as:
 npm install pseudo-localization
 ```
 
-### Manual Installation
+### Copy The Source Code
 
 Copy the files from [`src`](https://github.com/tryggvigy/pseudo-localization/blob/master/src) and use them directly.
 
@@ -148,13 +148,7 @@ stop();
 A command-line interface (CLI) is available for quick testing and automation.
 
 ```sh
-npx pseudo-localization ./path/to/file.json
-
-# Pipe a string
-echo "hello world" | npx pseudo-localization
-
-# Direct input
-npx pseudo-localization -i "hello world"
+npx pseudo-localization "hello world"
 ```
 
 ### CLI Options
@@ -163,13 +157,11 @@ npx pseudo-localization -i "hello world"
 pseudo-localization [src] [options]
 
 Positionals:
-  src  Input file or STDIN
+  src  Input string
 
 Options:
-  -o, --output  Output file (defaults to STDOUT)
   --strategy    Localization strategy (accented or bidi)
   --help        Show help
-  --version     Show version
 ```
 
 ---

package/dist/bin/pseudo-localize.d.ts

@@ -0,0 +1,2 @@
+#! /usr/bin/env node
+export {};

package/dist/bin/pseudo-localize.js

@@ -0,0 +1,25 @@
+#! /usr/bin/env node
+import yargs from 'yargs/yargs';
+import { hideBin } from 'yargs/helpers';
+import { pseudoLocalizeString } from "../localize.js";
+yargs(hideBin(process.argv))
+    .usage('$0 <string> [options]', 'Pseudo localize a string', (yargs) => {
+    return yargs
+        .positional('string', {
+        describe: 'String to pseudo-localize',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('strategy', {
+        alias: 's',
+        type: 'string',
+        describe: 'Set the strategy for localization',
+        choices: ['accented', 'bidi'],
+        default: 'accented',
+    });
+}, ({ string, strategy }) => {
+    process.stdout.write(pseudoLocalizeString(string, { strategy }));
+})
+    .help()
+    .parse();
+//# sourceMappingURL=pseudo-localize.js.map

package/dist/bin/pseudo-localize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pseudo-localize.js","sourceRoot":"","sources":["../../src/bin/pseudo-localize.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,MAAM,aAAa,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACzB,KAAK,CACJ,uBAAuB,EACvB,0BAA0B,EAC1B,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,KAAK;SACT,UAAU,CAAC,QAAQ,EAAE;QACpB,QAAQ,EAAE,2BAA2B;QACrC,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC;SACD,MAAM,CAAC,UAAU,EAAE;QAClB,KAAK,EAAE,GAAG;QACV,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,mCAAmC;QAC7C,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,CAAU;QACtC,OAAO,EAAE,UAAmB;KAC7B,CAAC,CAAC;AACP,CAAC,EACD,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE;IACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;AACnE,CAAC,CACF;KACA,IAAI,EAAE;KACN,KAAK,EAAE,CAAC"}

package/dist/dom.d.ts

@@ -0,0 +1,32 @@
+import { type PseudoLocalizeStringOptions } from './localize.ts';
+type StartOptions = PseudoLocalizeStringOptions & {
+    /**
+     * Node tags to ignore in pseudo-localization.
+     *
+     * @default ['STYLE']
+     */
+    blacklistedNodeNames?: string[];
+    /**
+     * The element to pseudo-localize text within.
+     *
+     * @default document.body
+     */
+    root?: Node;
+};
+type StopFn = () => void;
+/**
+ * A container for pseudo-localization of the DOM.
+ *
+ * @example
+ * new PseudoLocalizeDom().start();
+ */
+export declare class PseudoLocalizeDom {
+    #private;
+    /**
+     * Start pseudo-localizing the DOM.
+     *
+     * Returns a stop function to disable pseudo-localization.
+     */
+    start({ strategy, blacklistedNodeNames, root, }?: StartOptions): StopFn;
+}
+export {};

package/dist/dom.js

@@ -0,0 +1,106 @@
+import { pseudoLocalizeString, } from "./localize.js";
+function isNonEmptyString(str) {
+    return !!str && typeof str === 'string';
+}
+/**
+ * A container for pseudo-localization of the DOM.
+ *
+ * @example
+ * new PseudoLocalizeDom().start();
+ */
+export class PseudoLocalizeDom {
+    /**
+     * Indicates which elements the pseudo-localization is currently running on.
+     */
+    #enabledOn = new WeakSet();
+    /**
+     * Start pseudo-localizing the DOM.
+     *
+     * Returns a stop function to disable pseudo-localization.
+     */
+    start({ strategy = 'accented', blacklistedNodeNames = ['STYLE'], root, } = {}) {
+        const rootEl = root ?? document.body;
+        if (this.#enabledOn.has(rootEl)) {
+            console.warn(`Start aborted. pseudo-localization is already enabled on`, rootEl);
+            return () => { };
+        }
+        const observerConfig = {
+            characterData: true,
+            childList: true,
+            subtree: true,
+        };
+        const textNodesUnder = (node) => {
+            const walker = document.createTreeWalker(node, NodeFilter.SHOW_TEXT, (node) => {
+                const isAllWhitespace = node.nodeValue && !/[^\s]/.test(node.nodeValue);
+                if (isAllWhitespace) {
+                    return NodeFilter.FILTER_REJECT;
+                }
+                const isBlacklistedNode = node.parentElement &&
+                    blacklistedNodeNames.includes(node.parentElement.nodeName);
+                if (isBlacklistedNode) {
+                    return NodeFilter.FILTER_REJECT;
+                }
+                return NodeFilter.FILTER_ACCEPT;
+            });
+            let currNode;
+            const textNodes = [];
+            while ((currNode = walker.nextNode()))
+                textNodes.push(currNode);
+            return textNodes;
+        };
+        const pseudoLocalize = (node) => {
+            const textNodesUnderElement = textNodesUnder(node);
+            for (const textNode of textNodesUnderElement) {
+                const nodeValue = textNode.nodeValue;
+                if (isNonEmptyString(nodeValue)) {
+                    textNode.nodeValue = pseudoLocalizeString(nodeValue, { strategy });
+                }
+            }
+        };
+        // Pseudo localize the DOM
+        pseudoLocalize(document.body);
+        // Start observing the DOM for changes and run
+        // pseudo localization on any added text nodes
+        const observer = new MutationObserver((mutationsList) => {
+            for (const mutation of mutationsList) {
+                if (mutation.type === 'childList' && mutation.addedNodes.length > 0) {
+                    // Turn the observer off while performing dom manipulation to prevent
+                    // infinite dom mutation callback loops
+                    observer.disconnect();
+                    // For every node added, recurse down it's subtree and convert
+                    // all children as well
+                    mutation.addedNodes.forEach(pseudoLocalize.bind(this));
+                    observer.observe(document.body, observerConfig);
+                }
+                else if (mutation.type === 'characterData') {
+                    const nodeValue = mutation.target.nodeValue;
+                    const isBlacklistedNode = !!mutation.target.parentElement &&
+                        blacklistedNodeNames.includes(mutation.target.parentElement.nodeName);
+                    if (isNonEmptyString(nodeValue) && !isBlacklistedNode) {
+                        // Turn the observer off while performing dom manipulation to prevent
+                        // infinite dom mutation callback loops
+                        observer.disconnect();
+                        // The target will always be a text node so it can be converted
+                        // directly
+                        mutation.target.nodeValue = pseudoLocalizeString(nodeValue, {
+                            strategy,
+                        });
+                        observer.observe(document.body, observerConfig);
+                    }
+                }
+            }
+        });
+        observer.observe(document.body, observerConfig);
+        this.#enabledOn.add(rootEl);
+        const stop = () => {
+            if (!this.#enabledOn.has(rootEl)) {
+                console.warn('Stop aborted. pseudo-localization is not running on', rootEl);
+                return;
+            }
+            observer.disconnect();
+            this.#enabledOn.delete(rootEl);
+        };
+        return stop;
+    }
+}
+//# sourceMappingURL=dom.js.map

package/dist/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"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"}

package/dist/localize.d.ts

@@ -0,0 +1,28 @@
+export type Strategy = 'accented' | 'bidi';
+export type PseudoLocalizeStringOptions = {
+    /**
+     * The strategy to employ.
+     * - `accented`:
+     *   In Accented English all Latin letters are replaced by accented
+     *   Unicode counterparts which don't impair the readability of the content.
+     *   This allows developers to quickly test if any given string is being
+     *   correctly displayed in its 'translated' form.  Additionally, simple
+     *   heuristics are used to make certain words longer to better simulate the
+     * experience of international users.
+     * - `bidi`:
+     *  Bidi English is a fake [RTL](https://developer.mozilla.org/en-US/docs/Glossary/rtl) locale.
+     *  All words are surrounded by
+     *  Unicode formatting marks forcing the RTL directionality of characters.
+     *  In addition, to make the reversed text easier to read, individual
+     *  letters are flipped.
+     */
+    strategy?: Strategy;
+};
+/**
+ * Pseudo-localizes a string using a specified strategy.
+ *
+ * @example
+ * pseudoLocalizeString('orange'); // 'ǿǿřȧȧƞɠḗḗ'
+ * pseudoLocalizeString('orange', {strategy: 'bidi'}); // 'ǝƃuɐɹo'
+ */
+export declare const pseudoLocalizeString: (string: string, { strategy }?: PseudoLocalizeStringOptions) => string;

package/dist/localize.js

@@ -0,0 +1,67 @@
+/* prettier-ignore */
+const ACCENTED_MAP = {
+    a: 'ȧ', A: 'Ȧ', b: 'ƀ', B: 'Ɓ', c: 'ƈ', C: 'Ƈ', d: 'ḓ', D: 'Ḓ', e: 'ḗ', E: 'Ḗ',
+    f: 'ƒ', F: 'Ƒ', g: 'ɠ', G: 'Ɠ', h: 'ħ', H: 'Ħ', i: 'ī', I: 'Ī', j: 'ĵ', J: 'Ĵ',
+    k: 'ķ', K: 'Ķ', l: 'ŀ', L: 'Ŀ', m: 'ḿ', M: 'Ḿ', n: 'ƞ', N: 'Ƞ', o: 'ǿ', O: 'Ǿ',
+    p: 'ƥ', P: 'Ƥ', q: 'ɋ', Q: 'Ɋ', r: 'ř', R: 'Ř', s: 'ş', S: 'Ş', t: 'ŧ', T: 'Ŧ',
+    v: 'ṽ', V: 'Ṽ', u: 'ŭ', U: 'Ŭ', w: 'ẇ', W: 'Ẇ', x: 'ẋ', X: 'Ẋ', y: 'ẏ', Y: 'Ẏ',
+    z: 'ẑ', Z: 'Ẑ',
+};
+/* prettier-ignore */
+const BIDI_MAP = {
+    a: 'ɐ', A: '∀', b: 'q', B: 'Ԑ', c: 'ɔ', C: 'Ↄ', d: 'p', D: 'ᗡ', e: 'ǝ', E: 'Ǝ',
+    f: 'ɟ', F: 'Ⅎ', g: 'ƃ', G: '⅁', h: 'ɥ', H: 'H', i: 'ı', I: 'I', j: 'ɾ', J: 'ſ',
+    k: 'ʞ', K: 'Ӽ', l: 'ʅ', L: '⅂', m: 'ɯ', M: 'W', n: 'u', N: 'N', o: 'o', O: 'O',
+    p: 'd', P: 'Ԁ', q: 'b', Q: 'Ò', r: 'ɹ', R: 'ᴚ', s: 's', S: 'S', t: 'ʇ', T: '⊥',
+    u: 'n', U: '∩', v: 'ʌ', V: 'Ʌ', w: 'ʍ', W: 'M', x: 'x', X: 'X', y: 'ʎ', Y: '⅄',
+    z: 'z', Z: 'Z',
+};
+const strategies = {
+    accented: {
+        prefix: '',
+        postfix: '',
+        map: ACCENTED_MAP,
+        elongate: true,
+    },
+    bidi: {
+        // Surround words with Unicode formatting marks forcing
+        // right-to-left directionality of characters
+        prefix: '\u202e',
+        postfix: '\u202c',
+        map: BIDI_MAP,
+        elongate: false,
+    },
+};
+/**
+ * Pseudo-localizes a string using a specified strategy.
+ *
+ * @example
+ * pseudoLocalizeString('orange'); // 'ǿǿřȧȧƞɠḗḗ'
+ * pseudoLocalizeString('orange', {strategy: 'bidi'}); // 'ǝƃuɐɹo'
+ */
+export const pseudoLocalizeString = (string, { strategy = 'accented' } = {}) => {
+    const opts = strategies[strategy];
+    let pseudoLocalizedText = '';
+    for (const character of string) {
+        if (character in opts.map) {
+            const char = character;
+            const cl = char.toLowerCase();
+            // duplicate "a", "e", "o" and "u" to emulate ~30% longer text
+            if (opts.elongate &&
+                (cl === 'a' || cl === 'e' || cl === 'o' || cl === 'u')) {
+                pseudoLocalizedText += opts.map[char] + opts.map[char];
+            }
+            else
+                pseudoLocalizedText += opts.map[char];
+        }
+        else
+            pseudoLocalizedText += character;
+    }
+    // Add pre/postfix if the string does not already contain them respectively.
+    const prefix = pseudoLocalizedText.startsWith(opts.prefix) ? '' : opts.prefix;
+    const postfix = pseudoLocalizedText.endsWith(opts.postfix)
+        ? ''
+        : opts.postfix;
+    return prefix + pseudoLocalizedText + postfix;
+};
+//# sourceMappingURL=localize.js.map

package/dist/localize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localize.js","sourceRoot":"","sources":["../src/localize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,37 +1,38 @@
 {
   "name": "pseudo-localization",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "pseudo-localization for internationalization testing",
   "files": [
-    "bin",
-    "src/localize.mjs",
-    "src/dom.mjs"
+    "dist",
+    "src"
   ],
-  "main": "./src/localize.mjs",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
-      "import": "./src/localize.mjs"
+      "types": "./dist/localize.d.ts",
+      "import": "./dist/localize.js"
     },
     "./dom": {
-      "import": "./src/dom.mjs"
+      "types": "./dist/dom.d.ts",
+      "import": "./dist/dom.js"
     }
   },
   "bin": {
-    "pseudo-localization": "./bin/pseudo-localize.mjs"
+    "pseudo-localization": "./dist/bin/pseudo-localize.js"
   },
   "engines": {
     "node": "^23"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "check-formatting": "prettier --list-different src/**/*.ts",
+    "format": "prettier --write src/**/*.ts",
+    "lint": "eslint src/**/*.ts",
     "start": "node devserver.mjs",
-    "check-formatting": "prettier --list-different src/**/*.mjs",
-    "format": "prettier --write src/**/*.mjs",
-    "lint": "eslint src/**/*.mjs",
-    "test-js": "node ./src/localize.test.mjs",
-    "test": "npm run test-js jest && npm run check-formatting && npm run check-types && npm run lint",
-    "check-types": "tsc --noEmit",
-    "tsc": "tsc"
+    "test-js": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test './src/**/*.test.ts'",
+    "test": "npm run test-js && npm run check-formatting && npm run typecheck && npm run lint",
+    "typecheck": "tsc -p tsconfig.lib.json --noEmit"
   },
   "author": "Tryggvi Gylfason (http://twitter.com/tryggvigy)",
   "keywords": [
@@ -53,6 +54,7 @@
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@types/node": "^22.10.2",
+    "@types/yargs": "^17.0.33",
     "eslint": "^9.17.0",
     "globals": "^15.13.0",
     "prettier": "^3.4.2",

package/{bin/pseudo-localize.mjs → src/bin/pseudo-localize.ts}

@@ -2,7 +2,7 @@
 
 import yargs from 'yargs/yargs';
 import { hideBin } from 'yargs/helpers';
-import { pseudoLocalizeString } from '../src/localize.mjs';
+import { pseudoLocalizeString } from '../localize.ts';
 
 yargs(hideBin(process.argv))
   .usage(
@@ -13,13 +13,14 @@ yargs(hideBin(process.argv))
         .positional('string', {
           describe: 'String to pseudo-localize',
           type: 'string',
+          demandOption: true,
         })
         .option('strategy', {
           alias: 's',
           type: 'string',
           describe: 'Set the strategy for localization',
-          choices: ['accented', 'bidi'],
-          default: 'accented',
+          choices: ['accented', 'bidi'] as const,
+          default: 'accented' as const,
         });
     },
     ({ string, strategy }) => {
@@ -27,5 +28,4 @@ yargs(hideBin(process.argv))
     }
   )
   .help()
-  .version()
   .parse();

package/src/{dom.mjs → dom.ts}

@@ -1,30 +1,28 @@
-import { pseudoLocalizeString } from './localize.mjs';
+import {
+  pseudoLocalizeString,
+  type PseudoLocalizeStringOptions,
+} from './localize.ts';
 
-/**
- * Checks if the given value is a non-empty string.
- * @param {unknown} str - The value to check.
- * @returns {str is string} `true` if the value is a non-empty string, otherwise `false`.
- */
-function isNonEmptyString(str) {
+function isNonEmptyString(str: string | null | undefined): str is string {
   return !!str && typeof str === 'string';
 }
 
-/**
- * @typedef {import("./localize.mjs").PseudoLocalizeStringOptions} PseudoLocalizeStringOptions
- */
-
-/**
- * @typedef {Object} StartOnlyOptions
- * @property {string[]} [blacklistedNodeNames]
- * Node tags to ignore in pseudo-localization
- * @property {Node} [root]
- * The element to pseudo-localize text within.
- * Default: `document.body`
- */
+type StartOptions = PseudoLocalizeStringOptions & {
+  /**
+   * Node tags to ignore in pseudo-localization.
+   *
+   * @default ['STYLE']
+   */
+  blacklistedNodeNames?: string[];
+  /**
+   * The element to pseudo-localize text within.
+   *
+   * @default document.body
+   */
+  root?: Node;
+};
 
-/**
- * @typedef {StartOnlyOptions & PseudoLocalizeStringOptions} StartOptions
- */
+type StopFn = () => void;
 
 /**
  * A container for pseudo-localization of the DOM.
@@ -35,21 +33,20 @@ function isNonEmptyString(str) {
 export class PseudoLocalizeDom {
   /**
    * Indicates which elements the pseudo-localization is currently running on.
-   *
-   * @type {WeakSet<Node>}
    */
-  #enabledOn = new WeakSet();
+  #enabledOn = new WeakSet<Node>();
 
   /**
-   * @param {StartOptions} options
-   * @returns {() => void} stop
+   * Start pseudo-localizing the DOM.
+   *
+   * Returns a stop function to disable pseudo-localization.
    */
   start({
     strategy = 'accented',
     blacklistedNodeNames = ['STYLE'],
     root,
-  } = {}) {
-    let rootEl = root ?? document.body;
+  }: StartOptions = {}): StopFn {
+    const rootEl = root ?? document.body;
 
     if (this.#enabledOn.has(rootEl)) {
       console.warn(
@@ -65,10 +62,7 @@ export class PseudoLocalizeDom {
       subtree: true,
     };
 
-    /**
-     * @param {Node} node
-     */
-    const textNodesUnder = (node) => {
+    const textNodesUnder = (node: Node) => {
       const walker = document.createTreeWalker(
         node,
         NodeFilter.SHOW_TEXT,
@@ -96,12 +90,9 @@ export class PseudoLocalizeDom {
       return textNodes;
     };
 
-    /**
-     * @param {Node} element
-     */
-    const pseudoLocalize = (element) => {
-      const textNodesUnderElement = textNodesUnder(element);
-      for (let textNode of textNodesUnderElement) {
+    const pseudoLocalize = (node: Node) => {
+      const textNodesUnderElement = textNodesUnder(node);
+      for (const textNode of textNodesUnderElement) {
         const nodeValue = textNode.nodeValue;
         if (isNonEmptyString(nodeValue)) {
           textNode.nodeValue = pseudoLocalizeString(nodeValue, { strategy });
@@ -115,7 +106,7 @@ export class PseudoLocalizeDom {
     // Start observing the DOM for changes and run
     // pseudo localization on any added text nodes
     const observer = new MutationObserver((mutationsList) => {
-      for (let mutation of mutationsList) {
+      for (const mutation of mutationsList) {
         if (mutation.type === 'childList' && mutation.addedNodes.length > 0) {
           // Turn the observer off while performing dom manipulation to prevent
           // infinite dom mutation callback loops

package/src/localize.test.ts

@@ -0,0 +1,40 @@
+import test from 'node:test';
+import { strict as assert } from 'node:assert';
+import { pseudoLocalizeString as localize } from './localize.ts';
+
+test('accented', () => {
+  assert.equal(localize('abcd'), 'ȧȧƀƈḓ');
+  // aeou are duplicated
+  assert.equal(localize('aeou'), 'ȧȧḗḗǿǿŭŭ');
+  assert.equal(localize('foo bar'), 'ƒǿǿǿǿ ƀȧȧř');
+  assert.equal(localize('CAPITAL_LETTERS'), 'ƇȦȦƤĪŦȦȦĿ_ĿḖḖŦŦḖḖŘŞ');
+  // Everything except ASCII alphabet is passed through
+  assert.equal(localize('123,. n -~ðÞ'), '123,. ƞ -~ðÞ');
+});
+
+test('bidi', () => {
+  /**
+   * @type {{ strategy: 'bidi' }}
+   */
+  const bidi = {
+    strategy: 'bidi',
+  };
+
+  /**
+   * There are invisivle unicode formatting marks
+   * surrounding each output. For example
+   *
+   * "‮ɐqɔp‬" is actually "\u202e" + "ɐqɔp" + "\u202c"
+   *
+   * The presense of the formatting marks cause most UIs
+   * (likely including your text editor) to render the
+   * string backwards, if you will, or from right-to-left.
+   */
+  assert.equal(localize('abcd', bidi), '‮ɐqɔp‬');
+  assert.equal(localize('aeou', bidi), '‮ɐǝon‬');
+  assert.equal(localize('foo bar', bidi), '‮ɟoo qɐɹ‬');
+  assert.equal(localize('CAPITAL_LETTERS', bidi), '‮Ↄ∀ԀI⊥∀⅂_⅂Ǝ⊥⊥ƎᴚS‬');
+  assert.equal(localize('123,. n -~ðÞ', bidi), '‮123,. u -~ðÞ‬');
+  // formatting marks are not duplicated if already present
+  assert.equal(localize('‮ɟoo‬', bidi), '‮ɟoo‬');
+});

package/src/{localize.mjs → localize.ts}

@@ -35,41 +35,45 @@ const strategies = {
   },
 };
 
-/**
- * @typedef {'accented' | 'bidi'} Strategy
- */
+type Strategy = 'accented' | 'bidi';
 
-/**
- * @typedef {Object} PseudoLocalizeStringOptions
- * @property {Strategy} [strategy] The strategy to employ.
- * - `accented`: In Accented English all Latin letters are replaced by accented
- * Unicode counterparts which don't impair the readability of the content.
- * This allows developers to quickly test if any given string is being
- * correctly displayed in its 'translated' form.  Additionally, simple
- * heuristics are used to make certain words longer to better simulate the
- * experience of international users.
- * - `bidi`: Bidi English is a fake [RTL](https://developer.mozilla.org/en-US/docs/Glossary/rtl) locale.  All words are surrounded by
-Unicode formatting marks forcing the RTL directionality of characters.
-In addition, to make the reversed text easier to read, individual
-letters are flipped.
- */
+type PseudoLocalizeStringOptions = {
+  /**
+   * The strategy to employ.
+   * - `accented`:
+   *   In Accented English all Latin letters are replaced by accented
+   *   Unicode counterparts which don't impair the readability of the content.
+   *   This allows developers to quickly test if any given string is being
+   *   correctly displayed in its 'translated' form.  Additionally, simple
+   *   heuristics are used to make certain words longer to better simulate the
+   * experience of international users.
+   * - `bidi`:
+   *  Bidi English is a fake [RTL](https://developer.mozilla.org/en-US/docs/Glossary/rtl) locale.
+   *  All words are surrounded by
+   *  Unicode formatting marks forcing the RTL directionality of characters.
+   *  In addition, to make the reversed text easier to read, individual
+   *  letters are flipped.
+   */
+  strategy?: Strategy;
+};
 
 /**
  * Pseudo-localizes a string using a specified strategy.
- * @param {string} string - The string to pseudo-localize.
- * @param {PseudoLocalizeStringOptions} options - Options for pseudo-localization.
- * @returns {string} The pseudo-localized string.
+ *
+ * @example
+ * pseudoLocalizeString('orange'); // 'ǿǿřȧȧƞɠḗḗ'
+ * pseudoLocalizeString('orange', {strategy: 'bidi'}); // 'ǝƃuɐɹo'
  */
 export const pseudoLocalizeString = (
-  string,
-  { strategy = 'accented' } = {}
+  string: string,
+  { strategy = 'accented' }: PseudoLocalizeStringOptions = {}
 ) => {
-  let opts = strategies[strategy];
+  const opts = strategies[strategy];
 
   let pseudoLocalizedText = '';
-  for (let character of string) {
+  for (const character of string) {
     if (character in opts.map) {
-      const char = /** @type {keyof typeof opts.map} */ (character);
+      const char = character as keyof typeof opts.map;
       const cl = char.toLowerCase();
       // duplicate "a", "e", "o" and "u" to emulate ~30% longer text
       if (