<a id="dads-frameworkcopy"></a>

# @dads-framework/copy

The machinery every word a product says goes through, and no product's words.

A catalog entry is written side by side — `{ "orders.page.title": { en: "Orders" } }` — so one line holds a phrase in every language the product speaks, and adding a language is a column rather than a second file that can drift. Keys are derived from the catalog with `keyof typeof`, so a typo is a compile error rather than a screen that renders `orders.page.titel`.

<a id="try-it"></a>

## Try it

Install the copy library and its React 19 peers in your TypeScript app.

```sh
npm install @dads-framework/copy react@^19 react-dom@^19
```

Keep the catalog in the feature that owns the labels. Use `translate` when rendering a label.

```ts
import { defineCopy, translate } from "@dads-framework/copy";

const notesCopy = defineCopy({
  "notes.page.title": { en: "Notes" },
  "notes.action.add": { en: "Add note" },
});

console.log(translate(notesCopy, "en", "notes.page.title"));
console.log(translate(notesCopy, "en", "notes.action.add"));
```

The console prints `Notes` and then `Add note`. Change the key to `notes.page.titel` to see TypeScript reject the misspelling.

The [starter's workbench catalog](https://dadsframework.dev/docs/source/apps/kit-workbench/apps/web/copy/workbench-copy.ts) defines the notes and account labels and exposes a typed React hook that resolves the labels from their keys.

<a id="the-law-mechanism-here-words-with-the-product"></a>

## The law: mechanism here, words with the product

**No file in this kit defines a glossary entry or a refused word.** Not one noun, not one product name — those are a product's business, and a kit that held one product's vocabulary would be noise in every other. So `defineGlossary`, `glossaryCatalog`, `defineProductVocabulary` and `checkProductVocabulary` all take the words as an argument, and each application keeps its own words in its own package. Test fixtures can use sample vocabulary to exercise the checks.

**Here:** the types (`LocalizedText`, `CopyCatalog`, `defineCopy`), the resolver (`translate`, `createCopyHook`), the copy descriptor pure logic returns instead of a stitched sentence, the merge that refuses a duplicate key, the parity assertion that names the worklist when a locale is added, the locale provider and formatting seams, and the vocabulary sweep that judges a merged catalog against words handed to it.

**Not here:** any feature's words, and any product's vocabulary. Each feature lib owns its own catalog under `src/copy/`, which is what keeps editing an orders label from marking products affected. The app merges the catalogs at composition for **proof only** — the duplicate-key check and the vocabulary sweep. Nothing resolves a rendered string through the merged catalog, and a component that starts to would turn every label edit into an app-wide edit.

One English rule does live here and is worth naming out loud: `checkEnglishChromeCase` carries a list of initialisms that may stay all-caps (`API`, `CSV`, `SKU`, `SSO`…). That is a spelling allowlist for a typography rule, not a product's vocabulary — it decides how a word is capitalized, never whether the product may say it.

<a id="a-glossary-holds-the-shared-nouns"></a>

## A glossary holds the shared nouns

Each glossary entry carries a noun's singular and plural, so two features that name the same thing spell it identically.

Bare nouns reference glossary keys. **Whole sentences never do** — a sentence built by stitching a glossary noun into a template is a grammar bug waiting for the second language, so a sentence is one catalog entry written naturally in each locale.

<a id="scope-and-tags"></a>

## Scope and tags

`scope:shared` + `type:util`. The kit imports React and `Intl` and nothing else — no contracts, no client libs, no product — which is what lets a `scope:shared` `ui-primitives` lib reach it later without moving a boundary.

Canonical page: <https://dadsframework.dev/docs/package-copy>
