# Localeizer (/stuntkit/localeizer)

# Localeizer [#localeizer]

Localeizer rewrites text into American, British, Australian or Canadian
spelling, from source written in either American or British English. It ships
as the `@stunt-double/localeizer` package. Stunt Double's public sites are
written in American English and rewritten in the browser for visitors who read
British, Australian or Canadian spelling.

```ts
import { localiseSpelling } from "@stunt-double/localeizer";

localiseSpelling("Organize the color of the center.", "british");
// 'Organise the colour of the centre.'

localiseSpelling("Analyse the cancelled catalogue.", "american");
// 'Analyze the canceled catalog.'

localiseSpelling("Organise the colour of the centre.", "canadian");
// 'Organize the colour of the centre.'
```

Canadian spelling takes "-our", "-re" and the doubled "l" from British, and
"-ize", "-yze" and words such as "program" and "check" from American.

## Australian English [#australian-english]

Australian English spells like British English (`colour`, `organise`,
`centre`, `travelled`), so use the `'british'` system. There is no separate
`'australian'` value.

```ts
localiseSpelling("Organize a program to analyze the color of the center.", "british");
// 'Organise a program to analyse the colour of the centre.'
```

"Program" is left as written: it is correct in both systems, and it is the
usual Australian spelling for software too. The same goes for New Zealand,
Irish and most other Commonwealth English.

| Locale                                 | System       |
| -------------------------------------- | ------------ |
| `en-US`                                | `'american'` |
| `en-GB`, `en-AU`, `en-NZ`, `en-IE`     | `'british'`  |
| `en-CA`                                | `'canadian'` |

## Install [#install]

Add `@stunt-double:registry=https://npm.pkg.github.com` and a GitHub token with
`read:packages` to your `.npmrc`.

```sh
npm install @stunt-double/localeizer
```

<Callout variant="note" title="Moving from @stunt-double/spelling">
  The package was published as `@stunt-double/spelling` up to 0.1.0. The API
  is the same: swap the dependency and change the import path to
  `@stunt-double/localeizer`.
</Callout>

No dependencies. Runs anywhere JavaScript does: browsers, Node 20 or later
and workers.

## How it works [#how-it-works]

Every rewrite is a whole word, looked up exactly in a dictionary generated from
stems and the suffixes they take. Nothing is rewritten by pattern alone:
"promise", "enterprise" and "otherwise" keep their "-ise" in American English,
and "four" and "tour" keep their "-our". A word that isn't in the dictionary
stays as written.

- **Both directions.** A British word left in American copy still comes out
  American.
- **Ambiguous words are left alone.** Words correct in both systems with
  different meanings ("practice", "license", "check", "program") are never
  rewritten towards British.
- **Case is carried.** `Color` becomes `Colour` and `COLOR` becomes `COLOUR`.
- **Identifiers are kept.** A word in a domain, path, address or snake_case
  name (`color.com`, `/center`, `color_scheme`) keeps its spelling.
- **Identity on no change.** When nothing matches, the same string is
  returned, so you can compare by identity to skip a DOM write.

## API [#api]

- **`localiseSpelling(text, system)`** rewrites `text` into `system`
  (`'british' | 'american' | 'canadian'`).
- **`spellingDictionary(system)`** returns the lowercase word map for a system,
  useful for style checks and tooling.

Australia, New Zealand, Ireland and most of the Commonwealth use `'british'`
(see [Australian English](#australian-english)).

## Rewrite a page in the browser [#rewrite-a-page-in-the-browser]

```ts
import { localiseSpelling, type SpellingSystem } from "@stunt-double/localeizer";

function localisePage(root: Node, system: SpellingSystem): void {
  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
    const text = node.nodeValue ?? "";
    const next = localiseSpelling(text, system);
    if (next !== text) node.nodeValue = next;
  }
}
```

Skip `code`, `pre` and anything else where text isn't prose.

## Next steps [#next-steps]

- **[Read the full API on GitHub](https://github.com/stunt-double/stuntkit/tree/main/packages/localeizer)**