prosebook 0.1.0 → 0.3.0

package/README.md

@@ -32,15 +32,16 @@ const { t } = useCopy();
   2.5 KB gzipped.
 - **Checked.** Placeholders that drift between the source and a translation fail the build. A
   translation whose source has changed since is marked stale, automatically.
-- **Pruned.** A Vite build ships only the messages the code names.
+- **Pruned.** A Vite, Next.js or Bun build ships only the messages the code names, and fails on a
+  read whose key it can't see rather than show a key where a message was.
 - **Written well.** An optional lint holds the words to a writing guide: word budgets per kind of
   string, periods, sentence case, banned filler, and `{count} files` outside a plural. Plugins add your
   own rules, scoped by kind, surface and locale, and translations are held to their source.
+- **Native too.** The same catalog generates Rust, Swift and Kotlin for a tray, a menu bar or a CLI,
+  with plurals and number formats that say what the browser says.
 
 ## Quick start
 
-Not on npm yet: build it here (`bun run build`) and add it by path.
-
 ```bash
 bun add prosebook
 ```
@@ -66,6 +67,66 @@ import { prosebook } from 'prosebook/vite';
 export default defineConfig({ plugins: [react(), prosebook()] });
 ```
 
+Several apps that share one catalog each point the plugin at it: `prosebook({ root: '../../packages/copy' })`
+reads the config there and resolves its paths from there, so every app generates the same files.
+
+### With Next.js
+
+```ts
+// next.config.ts
+import { withProsebook } from 'prosebook/next';
+
+export default withProsebook({/* the rest of your Next config */});
+```
+
+`next dev` and `next build` generate first, and dev regenerates on every catalog edit: server
+components read the new text on their next render, and in the browser the messages change in
+place. A build ships only the messages the code names. It works with Turbopack, Next's default
+bundler, which doesn't resolve `./en.js` to `en.ts`, so set `importExtension: ''` in the prosebook
+config. In dev the [inspector](#finding-a-strings-entry) comes with it, with nothing to add to the app.
+
+### With Bun
+
+`Bun.serve`'s dev server bundles a page with the plugins bunfig.toml names, and regenerates and
+swaps the messages in place with this one:
+
+```toml
+# bunfig.toml
+[serve.static]
+plugins = ["prosebook/bun"]
+```
+
+In dev the page gets the [inspector](#finding-a-strings-entry) too. Its endpoints are routes for
+`Bun.serve` to spread into its own, imported only in dev:
+
+```ts
+// src/server.ts
+const dev = process.env.NODE_ENV !== 'production';
+
+Bun.serve({
+  routes: { ...(dev ? (await import('prosebook/bun')).inspector() : {}), '/': index },
+  development: dev && { hmr: true },
+});
+```
+
+The `bun build` command reads no plugins, so a build that prunes calls `Bun.build`, with
+`prosebook/bun` left `external` so the dev-only routes stay out of the bundle:
+
+```ts
+// build.ts
+import { prosebook } from 'prosebook/bun';
+
+await Bun.build({
+  entrypoints: ['./src/server.ts'],
+  target: 'bun',
+  outdir: './dist',
+  external: ['prosebook/bun'],
+  plugins: [prosebook()],
+});
+```
+
+TanStack Start, React Router and other frameworks built on Vite take the Vite plugin as it is.
+
 ### In React
 
 ```tsx
@@ -106,8 +167,133 @@ document.title = copy.t('app.title');
 copy.subscribe(() => render()); // after a locale switch, and in dev after a catalog edit
 ```
 
-Set `language: 'js'` in the config to generate `.js` modules with a `.d.ts` beside the index. On a
-server, create one `copy` per request.
+Set `language: 'js'` in the config to generate `.js` modules with a `.d.ts` beside the index, or
+`importExtension: '.ts'` to run the generated TypeScript in Node as it is.
+
+A message never throws. A placeholder with no value, or with one `Intl` refuses (an invalid date,
+`currency: 'euro'`), shows as `{name}` (`{$name}` in MF2), and the rest of the message renders. The
+problem goes to `console.error`, or to `onError` if you pass one:
+
+```js
+createCopy(catalog, { onError: (error, key, locale) => report(error, { key, locale }) });
+```
+
+### On a server
+
+Create one `copy` per request, in the locale it asks for, and wait for its messages.
+`acceptedLocales` reads an `Accept-Language` header into the locales it asks for, by weight, so
+`de;q=0.1, en;q=0.9` asks for English first:
+
+```ts
+import { acceptedLocales, createCopy } from 'prosebook';
+
+const copy = createCopy(catalog, { locale: acceptedLocales(request.headers.get('accept-language')) });
+await copy.ready;
+```
+
+**React Server Components** can't read context, so `prosebook/react/server` hands each request one
+copy that every server component in it shares. Your function is asked for the locale once per
+request, and React's `cache` keeps one request's copy from reaching another's:
+
+```ts
+// server-copy.ts, here with Next.js
+import { cookies, headers } from 'next/headers';
+import { acceptedLocales } from 'prosebook';
+import { createServerCopy } from 'prosebook/react/server';
+
+export const serverCopy = createServerCopy(catalog, async () => {
+  const picked = (await cookies()).get('locale')?.value;
+  const asked = acceptedLocales((await headers()).get('accept-language'));
+  return picked === undefined ? asked : [picked, ...asked];
+});
+```
+
+```tsx
+export default async function Page() {
+  const { t, locale } = await serverCopy(); // ready, in the locale negotiated for the request
+  return <h1 lang={locale}>{t('app.title')}</h1>;
+}
+```
+
+It's its own entry because `prosebook/react` creates a context when it loads, which the server
+build of React refuses. It needs React 19, where `cache` is.
+
+A page rendered on the server must hydrate in the same locale, so the browser's copy waits for its
+messages too. Create it above a `<Suspense>` boundary and wait below it: a component that suspends
+before it first mounts loses its state, copy included.
+
+```tsx
+function Providers({ locale, children }: { locale: Locale; children: ReactNode }) {
+  const [copy] = useState(() => createCopy(catalog, { locale }));
+  return (
+    <Suspense>
+      <Ready copy={copy}>{children}</Ready>
+    </Suspense>
+  );
+}
+
+function Ready({ copy, children }: { copy: Copy; children: ReactNode }) {
+  use(copy.ready);
+  return <CopyProvider copy={copy}>{children}</CopyProvider>;
+}
+```
+
+### Outside the browser: Rust, Swift and Kotlin
+
+The parts of an app the browser doesn't draw, a tray, a menu bar, a CLI, an Android shell, can read
+the same catalog. `generate` writes one file per target in `native`, holding every locale:
+
+```ts
+// prosebook.config.ts
+export default defineConfig({
+  native: [
+    { language: 'rust', out: 'src-tauri/src/copy.rs', keys: ['tray', 'menu'] },
+    { language: 'swift', out: 'mac/Sources/Copy.swift' },
+    { language: 'kotlin', out: 'android/app/src/main/java/shop/Copy.kt', package: 'shop' },
+  ],
+});
+```
+
+Each is an enum of the locales with a member per message, named for its key (`tray.recordings` is
+`tray_recordings` in Rust, `trayRecordings` in Swift and Kotlin). `keys` takes only the keys under
+those prefixes and names them without the prefix, so `tray.quit` above is `quit`:
+
+```rust
+mod copy;
+use copy::Locale;
+
+let copy = Locale::negotiate(&["de-AT", "en"]); // de-AT, then de, then the source
+let quit: &'static str = copy.quit();
+let count = copy.recordings(3); // "3 Aufnahmen": any integer or float
+```
+
+```swift
+let copy = Copy.negotiate(Locale.preferredLanguages)
+menu.title = copy.trayQuit
+label.stringValue = copy.trayRecordings(count: 3)
+```
+
+```kotlin
+val copy = Copy.negotiate(listOf(Locale.getDefault().toLanguageTag()))
+item.title = copy.trayQuit
+label.text = copy.trayRecordings(3)
+```
+
+A message with no placeholders is a `&'static str` in Rust and a property in Swift and Kotlin; one
+with placeholders is a function taking them in order, a string or a number of any integer or float type. Each member's doc comment
+is the source text, its context and what each argument holds.
+
+The files need nothing beside them: each brings the plural rules of its locales, compiled from CLDR's
+(the data `Intl.PluralRules` is built on), and its number formats, taken apart from `Intl` when it is
+generated: the digits, the separators, how integers group, the text around a currency or a percent.
+Each format is checked against `Intl` before any code is written, so native code writes what the
+browser does, Arabic digits and Indian grouping included. A key with no translation falls back
+through its parents to the source as the runtime's do, resolved when the file is written.
+
+What can't be written that way fails `generate`, with the fix: a date (pass it formatted, as a plain
+`{when}`), a tag, compact notation, significant digits, a unit or currency name that changes with the
+count (`unitDisplay: 'long'`), and an MF2 option read from an argument. Leave such keys out of the
+target's `keys`.
 
 ## The catalog
 
@@ -126,7 +312,8 @@ One file per area, `copy/catalog/<area>.yaml`. A key's first segment names its f
 | `comment`  | A change asked of whoever edits the entry next. A warning until it is made and the comment deleted.      |
 | `remove`   | `true` asks for the entry to go, with its translations and the code that reads it. A warning until then. |
 
-`key: message` is the shorthand for an entry with nothing to say about itself (set `require: []`).
+`key: message` is the shorthand for an entry with nothing to say about itself (set `require: []`;
+the schema offers it only then).
 Kinds and surfaces are configurable; `prosebook generate` writes `catalog.schema.json` beside the
 catalog, so an editor with the YAML language server completes and explains every field:
 
@@ -146,12 +333,14 @@ en: '{mode, select, dark {Dark} other {Light}}' # mode: 'dark' | (string & {})
 en: '{size, number, ::.0 unit/megabyte}' # 1.4 MB
 en: '{total, number, ::currency/EUR}' # €9.00
 en: '{when, date, medium} at {when, time, short}' # Oct 28, 2026 at 2:05 PM
+en: '{when, date, ::yMMMdjmm}' # Oct 28, 2026, 2:05 PM; 28. Okt. 2026, 14:05 in German
 en: 'By checking out you agree to our <link>terms</link>.' # a tag: an element inside the sentence
 ```
 
 A placeholder holds a number, a name or something a person typed, never a translated fragment: a
-word that changes with the sentence belongs in a `plural` or `select` arm. A skeleton the formatter
-would silently drop (`::compact-shortt`) fails the build instead of reaching the screen unformatted.
+word that changes with the sentence belongs in a `plural` or `select` arm. A skeleton's `j` is the
+hour as each locale writes it, 12 or 24. A skeleton the formatter would silently drop
+(`::compact-shortt`, a date's `J`) fails the build instead of reaching the screen unformatted.
 
 **Tags** keep a sentence with a link or bold run inside it as one entry, so a translator can move the
 element. `t()` renders a tag as its text; `rich()` and `<Text>` render it through a function. Tags
@@ -194,14 +383,40 @@ en: |-
 
 A message with `.match` holds whole sentences per variant, so a translator never stitches a sentence
 from an arm and the text around it. Several selectors pick the variant MF2's rules pick: the best
-match on the first, then the next, an exact number beating its plural category. `:offset` covers
-MF1's plural offset.
+match on the first, then the next, an exact number beating its plural category. A number is matched
+as it's shown: under `.input {$n :number minimumFractionDigits=1}`, 1 shows as "1.0", which English
+counts as `other`. `:integer` matches the value rounded, and `:percent` matches it times 100.
+`:offset` covers MF1's plural offset.
 
 The functions are MF2's defaults: `:string`, `:number`, `:integer`, `:percent`, `:currency`, `:unit`,
 `:offset`, and the date and time functions `:date`, `:time` and `:datetime`, which are still a draft
-in the spec and follow it as the `messageformat` package does. Option values are literals, since
-formatting is settled at build time; `currency=$code` is refused with that reason. Placeholders
-aren't wrapped in bidi isolation marks.
+in the spec and follow it as the `messageformat` package does. `.match` selects with `:number`,
+`:integer`, `:percent` or `:string`.
+
+**Text direction.** In a locale written right to left, each placeholder is wrapped in Unicode
+isolation marks, so a value written the other way can't reorder the text around it. Without them, a
+Latin name in a Hebrew sentence can pull the punctuation after it to the wrong side. `u:dir` on an
+expression picks its direction (`{$name :string u:dir=ltr}`) and asks for isolation in any locale.
+`isolate: 'always'` in the config also isolates every string placeholder in left-to-right locales,
+as the spec's default does. `isolate: false` turns it off.
+
+**Options from arguments.** An option can take its value from an argument, so one message formats
+whatever currency the order is in:
+
+```yaml
+en: 'Total: {$price :currency currency=$code}' # t('cart.total', { price: 9, code: 'USD' }): $9.00
+en: 'Due {$when :time timeZone=$tz}'
+```
+
+The argument is typed with the rest (`code: string`; `currencyDisplay=$d` takes only the values the
+option does), and a translation must use it too. These options can come from an argument: `currency`,
+`currencyDisplay`, `currencySign`, `unit`, `unitDisplay`, `signDisplay`, `fractionDigits` and the
+other digit counts, `timeZone` and `calendar`. The rest, such as a date's `fields` or a number's
+`select`, decide what the formatter is, so they're written in the message and the message says so.
+Literal options are still settled at build time. The ones from arguments are merged in as the
+message renders, and each locale keeps one formatter per distinct value. A value `Intl` refuses,
+such as `code: 'euro'`, throws a `RangeError` there. MF1 has no way to say this, so `migrate 1`
+stops at such a message.
 
 **Switching.** `prosebook migrate 2` rewrites the catalog and every translation in MF2, and
 `prosebook migrate 1` goes back. It's a dry run unless `--write`; then set `messageFormat` in the
@@ -231,7 +446,8 @@ still hold:
 
 ```bash
 prosebook status            # coverage and stale counts per locale
-prosebook todo de           # missing and stale entries, with context, ready to translate
+prosebook todo de > de.yaml # missing and stale entries, with context, ready to translate
+prosebook import de de.yaml # each filled-in entry into its file, checked first
 prosebook accept de cart.items
 ```
 
@@ -246,6 +462,7 @@ de           13/14  92%        1      2
 
 $ prosebook todo de
 # The button on a product that adds one to the cart.
+# kind: action, surface: action
 # en: Add one to cart
 # stale, the source changed: Add {+one +}to cart
 cart.add: In den Warenkorb
@@ -253,6 +470,23 @@ cart.add: In den Warenkorb
 
 Stale translations still show by default; `stale: 'fallback'` shows the source instead.
 
+**Translating with a model.** prosebook calls no model itself. `prosebook todo de --prompt` prints
+the same entries as a prompt for whichever model you use: how to reply, the plural forms German
+takes, what each kind of string and surface asks for, and how to treat a stale entry. Hand it to the
+model and give its reply to `import`, as a file or on stdin:
+
+```bash
+prosebook todo de --prompt | pbcopy  # paste into a chat, or hand it to an agent
+prosebook import de reply.md         # the YAML block is read out of the reply
+```
+
+`import` checks every entry as the whole catalog before writing it. One whose placeholders, tags
+or syntax don't hold is left out with its fix, which you can give back to the model, and the rest
+are written. A stale translation given back unchanged is accepted as still right. The imported
+translations are then linted, as a person's would be. An agent working in the repository needs none
+of this: it can read `prosebook todo de`, write the translation files itself, and run
+`prosebook check`.
+
 **Pseudo-locale.** `pseudo: 'en-XA'` generates `⟦Ýóóúúŕ çááŕţ⟧` from the source. Switch to it and
 any plain text on screen is hardcoded, a missing bracket is clipped text, and brackets inside
 brackets are a sentence spliced from fragments.
@@ -290,8 +524,9 @@ writes them, in the case of the words they replace, wherever in the message they
 checked as the whole catalog first, and nothing is written if any would break it. Only the message
 changes: a `key: message` entry stays one, and quoting and comments elsewhere stay as they were.
 
-`strict` adds sentence case, contractions, em-dashes, `…`, American spelling and a list of filler
-and marketing words. Add your own `banned`, `spelling` and `concepts` (one word per concept:
+`strict` adds sentence case, contractions, em-dashes, `…`, American spelling, paths written with one
+separator (`Settings › General`, not `→` or `>`; set `pathSeparator`) and a list of filler and
+marketing words. Add your own `banned`, `spelling` and `concepts` (one word per concept:
 `{ tablet: 'device' }`), and `properNouns` for sentence case. Where a rule is wrong about an
 entry, say why:
 
@@ -307,10 +542,16 @@ legal.privacy:
 A reason that is a shrug (`Intentional.`) fails, and so does an exemption the entry no longer needs.
 An exemption covers the entry in every locale, and is needed while any of them needs it.
 
+Where a rule is wrong about a whole area, set its severity there. A key's first segment is its area:
+
+```ts
+lint: { areas: { native: { 'sentence-case': 'off' } } }, // menu bars and trays write Title Case
+```
+
 **Lint plugins.** A plugin's rules are named `<plugin>/<rule>` in `lint.rules` and `allow`. A rule
 is given the entry and its readings: `primary` takes every `other` arm, `variants` holds one reading
 per plural or select arm, and `skeleton` only the words every arm carries. Placeholders and verbatim
-tags (`code`, `kbd`, ...) read as `HOLE`. `on` limits a rule to kinds or surfaces, and says which
+tags (`code`, `kbd`, ...) read as `HOLE`. `on` limits a rule to kinds, surfaces or areas, and says which
 locales it reads: the source when unset, `'all'`, or a list of languages (`['de']` covers `de-CH`).
 A rule is then given the `locale`, that locale's `ast` and `text`, and the `source` readings to
 compare with. `recommended` is its severity under that preset (off when unset), `strict` under
@@ -484,13 +725,22 @@ the singular is the plural less its `s`, `es` or `ies`.
 ## Pruning
 
 The Vite plugin replaces each locale module in a build with only the messages some module
-references. A reference is any string literal equal to a key, so keys kept in arrays or maps count;
+references. Next's Turbopack and Bun load a locale before the code that reads it, so their
+integrations read the source under `scan.dirs` instead, and every key a file there names is kept. A reference is any string literal equal to a key, so keys kept in arrays or maps count;
 ``t(`status.${state}`)`` and `t('status.' + state)` keep every key under `status.`. For keys built
 some other way, list them: `prosebook({ keep: ['plan.*'] })`.
 
+A message the build leaves out shows as its key, so by default a build fails on any read whose key
+it can't see: `t(item.key)`, ``rich(`${area}.title`)``, `<Text id={id} />`. Write the key at the read,
+or, where every key it reads is written elsewhere (in an array, say) or listed in `keep`, mark the
+line with `prosebook-ignore`. Reads are known by name: `t` and `rich` alone or as methods, the names
+they're destructured to (`const { rich: tRich } = copy`) in any module, and `<Text>` from
+`prosebook/react`. `prune: 'loose'` prunes without the check, and `prune: false` ships everything.
+`prune` and `keep` are options of each integration.
+
 ## Finding a string's entry
 
-In dev, hold Alt (Option on a Mac) and point at text on the page: the Vite plugin outlines the
+In dev, hold Alt (Option on a Mac) and point at text on the page: the inspector outlines the
 string and names its key and the locale it came from. Alt-click opens its entry in your editor: the
 translation for a translated string, the catalog entry for one that fell back. Alt-Shift-click opens
 the catalog entry either way. Save, and the string changes on the page, which keeps its locale and
@@ -520,10 +770,17 @@ Nothing is added to the page to make this work. In dev the runtime reports each
 and the inspector matches the text under the pointer back to it, so `t()`, `<Text>`, a sentence with
 a link inside it and readable attributes (`placeholder`, `title`, `aria-label`, `alt`) all work. Text
 the code changes after reading it (`t('…').toUpperCase()`) can't be traced. Where two keys read the
-same text, the label says so and the click opens the one read last.
-
-The editor is the one Vite's `/__open-in-editor` launches: one it finds running, or the command in
-`LAUNCH_EDITOR`. Turn the inspector off with `prosebook({ inspect: false })`.
+same text, the label says so and the click opens the one read last. Under Next.js, only text read in
+the browser is found: a server component's reads happen where the inspector can't see them.
+
+The inspector comes with each integration, in dev only, and opens the editor its dev server already
+launches. Under Vite, and so in any framework built on it, TanStack Start among them, that is the one
+`/__open-in-editor` launches: one it finds running, or the command in `LAUNCH_EDITOR`. Under Next.js
+it is the one `/__nextjs_launch-editor` launches, from `REACT_EDITOR` or one it finds running; the
+endpoints are served on a local port of their own, which a rewrite of `/__prosebook/*` sends to.
+Under Bun it is the one `Bun.openInEditor` finds, from `VISUAL`, `EDITOR` or bunfig.toml's
+`[debug] editor`, and the endpoints are the `inspector()` routes [above](#with-bun). Turn it off with
+`inspect: false` in the options of the Vite plugin, `withProsebook` or the Bun plugin.
 
 ## Config
 
@@ -538,6 +795,7 @@ export default defineConfig({
   lock: 'copy/lock.json',
   source: 'en',
   messageFormat: 1, // or 2, for Unicode MessageFormat 2
+  isolate: 'rtl', // MF2: isolate placeholders in right-to-left locales; 'always', or false
   bundled: [], // locales shipped in the main bundle; the rest load on first use
   pseudo: false, // or 'en-XA'
   stale: 'use', // or 'fallback'
@@ -546,50 +804,46 @@ export default defineConfig({
   require: ['context'],
   kinds: {/* name, action, description, state */},
   surfaces: {/* label, heading, tooltip, ... */},
-  lint: { extends: 'recommended', plugins: [], rules: {}, banned: [], spelling: {}, concepts: {}, properNouns: [] },
+  lint: {
+    extends: 'recommended',
+    plugins: [],
+    rules: {},
+    areas: {}, // severities per area: { native: { 'sentence-case': 'off' } }
+    banned: [],
+    spelling: {},
+    concepts: {},
+    properNouns: [],
+    pathSeparator: '›',
+  },
+  native: [], // Rust, Swift or Kotlin files: { language: 'rust', out: 'src/copy.rs', keys: ['tray'] }
   scan: { dirs: ['src'] },
 });
 ```
 
-## Example
+## Examples
+
+Each is a small shop in English, German and the pseudo-locale, and uses prosebook as an app would,
+from the package. CI generates, lints, typechecks and builds each one, then checks what its build
+serves.
 
-[`examples/react-app`](examples/react-app) is a small shop in English, German, a part-translated
-Turkish and the pseudo-locale.
+| Example                                              |                                                                                             |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [`examples/vite`](examples/vite)                     | React with Vite, and a part-translated Turkish. The inspector is on.                        |
+| [`examples/next`](examples/next)                     | Next.js: server components read a copy per request, client components the provider's.       |
+| [`examples/tanstack-start`](examples/tanstack-start) | TanStack Start, rendered on the server in the request's locale with the Vite plugin.        |
+| [`examples/bun`](examples/bun)                       | `Bun.serve` with a React page, a route that answers in the request's locale, the inspector. |
+| [`examples/node`](examples/node)                     | No framework and no bundler: a Node script prints a receipt from the generated TypeScript.  |
 
 ```bash
-bun run example
+bun run build                      # the examples import prosebook from dist
+bun run --cwd examples/next dev
 ```
 
-## Where it came from
-
-prosebook generalizes `@drasyn/text`, the catalog behind Drasyn's UI. It keeps that design: YAML
-entries with `kind`, `surface` and `context`, ICU checked at build time, generated types, tags for
-elements inside a sentence, a lint for the writing guide with reasoned exemptions, build-time
-pruning, and the YAML 1.1/1.2 divergence check. What changed:
-
-| Drasyn's text package                                       | prosebook                                                                   |
-| ----------------------------------------------------------- | --------------------------------------------------------------------------- |
-| Parses ICU at runtime with `intl-messageformat`             | Compiles messages to functions; no parser ships                             |
-| One global language; components don't re-render on a switch | `createCopy` instances; `useCopy()` re-renders; one per request on a server |
-| Falls back to English only                                  | Negotiates the locale and falls back key by key through parents             |
-| No way to know a translation is out of date                 | The lock marks stale translations; `status`, `todo`, `accept`               |
-| Kinds, surfaces and word lists are Drasyn's                 | All configurable; `recommended` and `strict` presets                        |
-| A rich message needs `rich: true` and a `RichText` wrapper  | Tags are detected; React output is keyed; default tags in the provider      |
-| Pruning fails the build on a key it can't read              | Pruning reads string literals and prefixes, so keys in data still work      |
-| Bun scripts inside one repo                                 | A CLI, a Vite plugin and `prosebook/tools` for other bundlers               |
-| —                                                           | Hardcoded-text `scan` and `extract`, pseudo-locale, translator `todo`       |
-| —                                                           | Alt-click a string in dev to open its entry                                 |
-
 ## Further
 
 Ideas not built yet, roughly in order of value:
 
-1. **Draft translations with an LLM**: `prosebook translate de --draft`, prompted with `context`,
-   `kind`, `surface` and `args`, written to a draft file a person reviews before it ships.
-2. **Exchange formats**: XLIFF 2 and JSON export and import for translation tools.
-3. **Per-area splitting**: one chunk per area and locale, so a lazy route loads only its own messages.
-4. **Server rendering helpers**: `Accept-Language` negotiation and a React Server Components reader.
-5. **Native targets**: generate Rust, Swift or Kotlin from the same catalog, as Drasyn generates
-   Rust for its tray and menus.
-6. **Variable MF2 options**: `{$price :currency currency=$code}`, compiled to a formatter cached per
-   value.
+1. **Exchange formats**: XLIFF 2 and JSON export and import for translation tools.
+2. **Per-area splitting**: one chunk per area and locale, so a lazy route loads only its own messages.
+3. **Dates in native targets**: date and time formats taken apart from `Intl` as number formats are,
+   so a Rust, Swift or Kotlin message can say when.

package/dist/bun.d.ts

@@ -0,0 +1,34 @@
+import { t as Prune } from "./bundle-KD-DiiFa.js";
+import { i as ProsebookConfig } from "./config-DdMkKt_N.js";
+import { BunPlugin } from "bun";
+export interface ProsebookBunOptions {
+  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */
+  config?: ProsebookConfig;
+  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */
+  root?: string;
+  /**
+   * In `Bun.build`, ship only the messages the code names. `strict`, the default, also fails the
+   * build on a read whose key it can't see, such as `t(item.key)`. `loose` prunes without that
+   * check; `false` ships every message.
+   */
+  prune?: Prune;
+  /** Keys a build always keeps, exactly or as `prefix.*`: for keys built at runtime from data. */
+  keep?: string[];
+  /** Under the dev server, Alt-click a string on the page to open its entry in the editor. On by default. */
+  inspect?: boolean;
+}
+export declare function prosebook(options?: ProsebookBunOptions): BunPlugin;
+export interface InspectorRoutesOptions {
+  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */
+  config?: ProsebookConfig;
+  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */
+  root?: string;
+}
+/**
+ * The inspector's endpoints as `Bun.serve` routes: `routes: { ...inspector(), '/': index }`. For dev
+ * only: they read and write the catalog.
+ */
+export declare function inspector(options?: InspectorRoutesOptions): Record<string, (req: Request) => Promise<Response>>;
+declare const _default: BunPlugin;
+export { _default as default };
+//# sourceMappingURL=bun.d.ts.map

package/dist/bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","names":[],"sources":["../src/bun.ts"],"mappings":";;;iBAqCiB;;EAEf,SAAS;;EAET;;;;;;EAMA,QAAQ;;EAER;;EAEA;;wBAQc,UAAU,UAAS,sBAA2B;iBA6C7C;;EAEf,SAAS;;EAET;;;;;;wBAOc,UAAU,UAAS,yBAA8B,gBAAgB,KAAK,YAAY,QAAQ"}

package/dist/bun.js

@@ -0,0 +1,98 @@
+import { a as installInspector, c as prunedModule, f as watchCatalog, i as hotLocale, l as scanSources, n as HOT_SET, o as keeper, r as beside, t as HOT_INDEX, u as unseenMessage } from "./bundle-DboItAre.js";
+import { n as generate, x as CatalogError } from "./generate-9pR3i5Bj.js";
+import { r as loadConfig } from "./config-BPSmoYel.js";
+import { t as inspectorEndpoints } from "./endpoints-CnUfCkIk.js";
+import { basename, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+// src/bun.ts
+/**
+* `prosebook/bun`: the catalog as part of a Bun build, or of Bun's dev server.
+*
+* Generates when the plugin is set up. Given to `Bun.build`, it ships only the messages the code
+* names: Bun loads a locale module before it has seen the code that reads it, so the keys come from
+* the source under `scan.dirs` (`tools/bundle.ts`) and each locale loads already pruned. The `bun
+* build` command reads no plugins, so a build that prunes is a script that calls `Bun.build`.
+*
+* Named in bunfig.toml's `[serve.static] plugins`, it serves `Bun.serve`'s bundler instead, which
+* names no entry points: it regenerates whenever a catalog or translation file changes, and each
+* locale module accepts its own update and hands the new messages to every copy, as under Vite. The
+* index starts the inspector on the page too, whose endpoints are `inspector()`'s routes, spread into
+* `Bun.serve`'s; an entry opens in the editor `Bun.openInEditor` finds.
+*/
+const inspectorPath = beside(import.meta.url, "inspector");
+const describe = (e) => e instanceof CatalogError ? e.message : e instanceof Error ? e.stack ?? e.message : String(e);
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function prosebook(options = {}) {
+	return {
+		name: "prosebook",
+		async setup(build) {
+			const config = await loadConfig(resolve(options.root ?? process.cwd()), options.config);
+			let generated = generate(config);
+			const folder = config.out.split(/[\\/]/).map(escape).join("[\\\\/]");
+			const filter = new RegExp(`^${folder}[\\\\/][^\\\\/]+\\.[jt]s$`);
+			const nameOf = (path) => basename(path).replace(/\.[jt]s$/, "");
+			if ("entrypoints" in build.config) {
+				const prune = options.prune ?? "strict";
+				if (prune === false) return;
+				const { refs, unseen } = scanSources(config, prune === "strict");
+				if (unseen.length > 0) throw new Error(unseenMessage(unseen, config.root));
+				const kept = keeper(refs, options.keep);
+				build.onLoad({ filter }, ({ path }) => {
+					const entries = generated.entries.get(nameOf(path));
+					return entries === void 0 ? void 0 : {
+						contents: prunedModule(entries, kept),
+						loader: "js"
+					};
+				});
+				return;
+			}
+			const dev = process.env.NODE_ENV !== "production";
+			const inspector = dev && options.inspect !== false ? installInspector(inspectorPath, "/") : "";
+			if (dev) watchCatalog(config, () => {
+				try {
+					generated = generate(config);
+				} catch (e) {
+					console.error(describe(e));
+				}
+			});
+			build.onLoad({ filter }, ({ path }) => {
+				const name = nameOf(path);
+				const loader = path.endsWith(".ts") ? "ts" : "js";
+				if (generated.entries.has(name)) return {
+					contents: readFileSync(path, "utf8") + hotLocale(name),
+					loader
+				};
+				return name === "index" ? {
+					contents: HOT_SET + inspector + readFileSync(path, "utf8") + HOT_INDEX,
+					loader
+				} : void 0;
+			});
+		}
+	};
+}
+/**
+* The inspector's endpoints as `Bun.serve` routes: `routes: { ...inspector(), '/': index }`. For dev
+* only: they read and write the catalog.
+*/
+function inspector(options = {}) {
+	const handle = inspectorEndpoints(loadConfig(resolve(options.root ?? process.cwd()), options.config), { open: ({ file, line, column }) => {
+		try {
+			Bun.openInEditor(file, {
+				line,
+				column
+			});
+			return new Response(null, { status: 204 });
+		} catch (e) {
+			return new Response(`${e instanceof Error ? e.message : String(e)}: set VISUAL or EDITOR to the editor's command`, { status: 500 });
+		}
+	} });
+	const route = async (req) => await handle(req) ?? new Response(null, { status: 404 });
+	return {
+		"/__prosebook/open": route,
+		"/__prosebook/entry": route
+	};
+}
+var bun_default = prosebook();
+export { bun_default as default, inspector, prosebook };
+
+//# sourceMappingURL=bun.js.map

package/dist/bun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.js","names":[],"sources":["../src/bun.ts"],"sourcesContent":["/**\n * `prosebook/bun`: the catalog as part of a Bun build, or of Bun's dev server.\n *\n * Generates when the plugin is set up. Given to `Bun.build`, it ships only the messages the code\n * names: Bun loads a locale module before it has seen the code that reads it, so the keys come from\n * the source under `scan.dirs` (`tools/bundle.ts`) and each locale loads already pruned. The `bun\n * build` command reads no plugins, so a build that prunes is a script that calls `Bun.build`.\n *\n * Named in bunfig.toml's `[serve.static] plugins`, it serves `Bun.serve`'s bundler instead, which\n * names no entry points: it regenerates whenever a catalog or translation file changes, and each\n * locale module accepts its own update and hands the new messages to every copy, as under Vite. The\n * index starts the inspector on the page too, whose endpoints are `inspector()`'s routes, spread into\n * `Bun.serve`'s; an entry opens in the editor `Bun.openInEditor` finds.\n */\nimport { readFileSync } from 'node:fs';\nimport { basename, resolve } from 'node:path';\n\nimport type { BunPlugin } from 'bun';\n\nimport {\n  beside,\n  HOT_INDEX,\n  HOT_SET,\n  hotLocale,\n  installInspector,\n  keeper,\n  prunedModule,\n  scanSources,\n  unseenMessage,\n  watchCatalog,\n  type Prune,\n} from './tools/bundle.ts';\nimport { CatalogError } from './tools/catalog.ts';\nimport { loadConfig, type ProsebookConfig } from './tools/config.ts';\nimport { inspectorEndpoints } from './tools/endpoints.ts';\nimport { generate } from './tools/generate.ts';\n\nexport interface ProsebookBunOptions {\n  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */\n  config?: ProsebookConfig;\n  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */\n  root?: string;\n  /**\n   * In `Bun.build`, ship only the messages the code names. `strict`, the default, also fails the\n   * build on a read whose key it can't see, such as `t(item.key)`. `loose` prunes without that\n   * check; `false` ships every message.\n   */\n  prune?: Prune;\n  /** Keys a build always keeps, exactly or as `prefix.*`: for keys built at runtime from data. */\n  keep?: string[];\n  /** Under the dev server, Alt-click a string on the page to open its entry in the editor. On by default. */\n  inspect?: boolean;\n}\n\nconst inspectorPath = beside(import.meta.url, 'inspector');\n\nconst describe = (e: unknown) => (e instanceof CatalogError ? e.message : e instanceof Error ? (e.stack ?? e.message) : String(e));\nconst escape = (s: string) => s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n\nexport function prosebook(options: ProsebookBunOptions = {}): BunPlugin {\n  return {\n    name: 'prosebook',\n    async setup(build) {\n      const config = await loadConfig(resolve(options.root ?? process.cwd()), options.config);\n      let generated = generate(config);\n      // The generated modules, by path as Bun gives it: either separator on Windows.\n      const folder = config.out.split(/[\\\\/]/).map(escape).join('[\\\\\\\\/]');\n      const filter = new RegExp(`^${folder}[\\\\\\\\/][^\\\\\\\\/]+\\\\.[jt]s$`);\n      const nameOf = (path: string) => basename(path).replace(/\\.[jt]s$/, '');\n\n      if ('entrypoints' in build.config) {\n        const prune = options.prune ?? 'strict';\n        if (prune === false) return;\n        const { refs, unseen } = scanSources(config, prune === 'strict');\n        if (unseen.length > 0) throw new Error(unseenMessage(unseen, config.root));\n        const kept = keeper(refs, options.keep);\n        build.onLoad({ filter }, ({ path }) => {\n          const entries = generated.entries.get(nameOf(path));\n          return entries === undefined ? undefined : { contents: prunedModule(entries, kept), loader: 'js' };\n        });\n        return;\n      }\n\n      const dev = process.env.NODE_ENV !== 'production';\n      const inspector = dev && options.inspect !== false ? installInspector(inspectorPath, '/') : '';\n      if (dev) {\n        watchCatalog(config, () => {\n          try {\n            generated = generate(config);\n          } catch (e) {\n            console.error(describe(e));\n          }\n        });\n      }\n      build.onLoad({ filter }, ({ path }) => {\n        const name = nameOf(path);\n        const loader = path.endsWith('.ts') ? 'ts' : 'js';\n        if (generated.entries.has(name)) return { contents: readFileSync(path, 'utf8') + hotLocale(name), loader };\n        return name === 'index' ? { contents: HOT_SET + inspector + readFileSync(path, 'utf8') + HOT_INDEX, loader } : undefined;\n      });\n    },\n  };\n}\n\nexport interface InspectorRoutesOptions {\n  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */\n  config?: ProsebookConfig;\n  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */\n  root?: string;\n}\n\n/**\n * The inspector's endpoints as `Bun.serve` routes: `routes: { ...inspector(), '/': index }`. For dev\n * only: they read and write the catalog.\n */\nexport function inspector(options: InspectorRoutesOptions = {}): Record<string, (req: Request) => Promise<Response>> {\n  const handle = inspectorEndpoints(loadConfig(resolve(options.root ?? process.cwd()), options.config), {\n    open: ({ file, line, column }) => {\n      try {\n        Bun.openInEditor(file, { line, column });\n        return new Response(null, { status: 204 });\n      } catch (e) {\n        return new Response(`${e instanceof Error ? e.message : String(e)}: set VISUAL or EDITOR to the editor's command`, { status: 500 });\n      }\n    },\n  });\n  const route = async (req: Request) => (await handle(req)) ?? new Response(null, { status: 404 });\n  return { '/__prosebook/open': route, '/__prosebook/entry': route };\n}\n\n// bunfig.toml names the module, and Bun takes its default export as the plugin.\nexport default prosebook();\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsDA,MAAM,gBAAgB,OAAO,YAAY,KAAK,WAAW;AAEzD,MAAM,YAAY,MAAgB,aAAa,eAAe,EAAE,UAAU,aAAa,QAAS,EAAE,SAAS,EAAE,UAAW,OAAO,CAAC;AAChI,MAAM,UAAU,MAAc,EAAE,QAAQ,uBAAuB,MAAM;AAErE,SAAgB,UAAU,UAA+B,CAAC,GAAc;CACtE,OAAO;EACL,MAAM;EACN,MAAM,MAAM,OAAO;GACjB,MAAM,SAAS,MAAM,WAAW,QAAQ,QAAQ,QAAQ,QAAQ,IAAI,CAAC,GAAG,QAAQ,MAAM;GACtF,IAAI,YAAY,SAAS,MAAM;GAE/B,MAAM,SAAS,OAAO,IAAI,MAAM,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,SAAS;GACnE,MAAM,SAAS,IAAI,OAAO,IAAI,OAAO,0BAA0B;GAC/D,MAAM,UAAU,SAAiB,SAAS,IAAI,CAAC,CAAC,QAAQ,YAAY,EAAE;GAEtE,IAAI,iBAAiB,MAAM,QAAQ;IACjC,MAAM,QAAQ,QAAQ,SAAS;IAC/B,IAAI,UAAU,OAAO;IACrB,MAAM,EAAE,MAAM,WAAW,YAAY,QAAQ,UAAU,QAAQ;IAC/D,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,MAAM,cAAc,QAAQ,OAAO,IAAI,CAAC;IACzE,MAAM,OAAO,OAAO,MAAM,QAAQ,IAAI;IACtC,MAAM,OAAO,EAAE,OAAO,IAAI,EAAE,WAAW;KACrC,MAAM,UAAU,UAAU,QAAQ,IAAI,OAAO,IAAI,CAAC;KAClD,OAAO,YAAY,KAAA,IAAY,KAAA,IAAY;MAAE,UAAU,aAAa,SAAS,IAAI;MAAG,QAAQ;KAAK;IACnG,CAAC;IACD;GACF;GAEA,MAAM,MAAM,QAAQ,IAAI,aAAa;GACrC,MAAM,YAAY,OAAO,QAAQ,YAAY,QAAQ,iBAAiB,eAAe,GAAG,IAAI;GAC5F,IAAI,KACF,aAAa,cAAc;IACzB,IAAI;KACF,YAAY,SAAS,MAAM;IAC7B,SAAS,GAAG;KACV,QAAQ,MAAM,SAAS,CAAC,CAAC;IAC3B;GACF,CAAC;GAEH,MAAM,OAAO,EAAE,OAAO,IAAI,EAAE,WAAW;IACrC,MAAM,OAAO,OAAO,IAAI;IACxB,MAAM,SAAS,KAAK,SAAS,KAAK,IAAI,OAAO;IAC7C,IAAI,UAAU,QAAQ,IAAI,IAAI,GAAG,OAAO;KAAE,UAAU,aAAa,MAAM,MAAM,IAAI,UAAU,IAAI;KAAG;IAAO;IACzG,OAAO,SAAS,UAAU;KAAE,UAAU,UAAU,YAAY,aAAa,MAAM,MAAM,IAAI;KAAW;IAAO,IAAI,KAAA;GACjH,CAAC;EACH;CACF;AACF;;;;;AAaA,SAAgB,UAAU,UAAkC,CAAC,GAAwD;CACnH,MAAM,SAAS,mBAAmB,WAAW,QAAQ,QAAQ,QAAQ,QAAQ,IAAI,CAAC,GAAG,QAAQ,MAAM,GAAG,EACpG,OAAO,EAAE,MAAM,MAAM,aAAa;EAChC,IAAI;GACF,IAAI,aAAa,MAAM;IAAE;IAAM;GAAO,CAAC;GACvC,OAAO,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC;EAC3C,SAAS,GAAG;GACV,OAAO,IAAI,SAAS,GAAG,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,EAAE,iDAAiD,EAAE,QAAQ,IAAI,CAAC;EACpI;CACF,EACF,CAAC;CACD,MAAM,QAAQ,OAAO,QAAkB,MAAM,OAAO,GAAG,KAAM,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC;CAC/F,OAAO;EAAE,qBAAqB;EAAO,sBAAsB;CAAM;AACnE;AAGA,IAAA,cAAe,UAAU"}