# Americanize (/stuntkit/americanize)

# Americanize [#americanize]

Americanize rewrites text into American, British, Australian or Canadian
spelling, from source written in either American or British English. It ships
as the `@stunt-double/spelling` 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/spelling";

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

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

## 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/spelling
```

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/spelling";

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/spelling)**