prosebook 0.1.0 → 0.3.0

package/src/cli.ts

@@ -3,24 +3,23 @@
  * The `prosebook` command. Each subcommand is a function of the resolved config; `check` runs the
  * ones CI needs in one go.
  */
-import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
-import { stringify } from 'yaml';
-
+import { watchCatalog } from './tools/bundle.ts';
 import { CatalogError, entryLocator, whereOf, type Catalog, type Problem } from './tools/catalog.ts';
 import { CONFIG_FILES, loadConfig, type ResolvedConfig } from './tools/config.ts';
-import { formatDiff, wordDiff } from './tools/diff.ts';
-import { applyFixes } from './tools/entry.ts';
+import { applyFixes, importTranslations } from './tools/entry.ts';
 import { applyExtract, planExtract } from './tools/extract.ts';
 import { generate, render } from './tools/generate.ts';
-import { lint } from './tools/lint.ts';
-import type { StaleTranslation } from './tools/lock.ts';
+import { lint, type Finding } from './tools/lint.ts';
+import { changeOf, type StaleTranslation } from './tools/lock.ts';
 import { applyMigrate, planMigrate } from './tools/migrate.ts';
 import { SarifReport } from './tools/sarif.ts';
 import { isReferenced, scan, sourceFiles } from './tools/scan.ts';
 import { SYNTAX_NAME } from './tools/syntax.ts';
+import { todoOf } from './tools/todo.ts';
 
 const HELP = `prosebook: every string your app shows, in one typed catalog
 
@@ -34,6 +33,9 @@ Commands:
   status                  Translation coverage and stale translations per locale  (--strict, --verbose)
   accept <locale> [keys]  Mark stale translations as still right  (--all for every stale one)
   todo <locale>           Print the missing and stale entries of a locale, ready to translate
+                          (--prompt: as a prompt for a model, saying how to reply)
+  import <locale> [file]  Write translations from todo's YAML filled in, or a model's reply to --prompt
+                          (stdin without a file); each is checked first, and one that fails is left out
   scan                    Find hardcoded text in JSX and catalog keys no code reads  (--strict)
   extract [paths]         Move hardcoded JSX text into the catalog and rewrite the code to read it
                           (dry run unless --write; --area <name> puts every entry in one area)
@@ -78,6 +80,7 @@ async function main(argv: string[]): Promise<number> {
       all: { type: 'boolean' },
       write: { type: 'boolean' },
       fix: { type: 'boolean' },
+      prompt: { type: 'boolean' },
       area: { type: 'string' },
       format: { type: 'string' },
       help: { type: 'boolean', short: 'h' },
@@ -119,7 +122,9 @@ async function main(argv: string[]): Promise<number> {
       case 'accept':
         return runAccept(config, rest, values.all === true);
       case 'todo':
-        return runTodo(config, rest[0]);
+        return runTodo(config, rest[0], values.prompt === true);
+      case 'import':
+        return runImport(config, rest[0], rest[1]);
       case 'scan':
         code = runScan(config, values.strict === true, report);
         break;
@@ -202,15 +207,7 @@ function watchMode(config: ResolvedConfig): Promise<number> {
     }
   };
   regenerate();
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  for (const dir of [config.catalog, config.locales]) {
-    if (!existsSync(dir)) continue;
-    watch(dir, { recursive: true }, (_event, file) => {
-      if (file === null || !file.endsWith('.yaml')) return;
-      clearTimeout(timer);
-      timer = setTimeout(regenerate, 50);
-    });
-  }
+  watchCatalog(config, regenerate);
   out('prosebook: watching the catalog for changes');
   return new Promise(() => {});
 }
@@ -231,12 +228,7 @@ function runLint(config: ResolvedConfig, report?: SarifReport, fix = false): num
       findings = lint(catalog.messages, config);
     }
   }
-  const locate = entryLocator(config.root);
-  const placed = findings.map((f) => ({ ...f, ...locate(f.file, f.key, f.at?.start, config.source) }));
-  for (const f of placed) {
-    const severity = f.severity === 'error' ? 'error' : 'warn ';
-    err(`${severity} ${f.file}:${f.line}:${f.column} ${f.key}: [${f.rule}] ${f.message}${f.fix === undefined ? '' : ' (fixable)'}`);
-  }
+  const placed = printFindings(config, findings);
   if (report !== undefined) {
     for (const [name, { rule }] of Object.entries(config.lint.rules)) report.rule(name, rule.description);
     report.rule('allow', RULES.allow);
@@ -264,6 +256,17 @@ function runLint(config: ResolvedConfig, report?: SarifReport, fix = false): num
   return errors > 0 ? 1 : 0;
 }
 
+/** Each finding on its line, placed at its entry's words. */
+function printFindings(config: ResolvedConfig, findings: Finding[]) {
+  const locate = entryLocator(config.root);
+  const placed = findings.map((f) => ({ ...f, ...locate(f.file, f.key, f.at?.start, config.source) }));
+  for (const f of placed) {
+    const severity = f.severity === 'error' ? 'error' : 'warn ';
+    err(`${severity} ${f.file}:${f.line}:${f.column} ${f.key}: [${f.rule}] ${f.message}${f.fix === undefined ? '' : ' (fixable)'}`);
+  }
+  return placed;
+}
+
 function missingKeys(catalog: Catalog, locale: string): string[] {
   return catalog.messages.filter((m) => !m.translations.has(locale)).map((m) => m.key);
 }
@@ -337,47 +340,46 @@ function runAccept(config: ResolvedConfig, args: string[], all: boolean): number
   return 0;
 }
 
-/** What changed in the source of a stale translation, as a word diff, or why that isn't known. */
-function changeOf(stale: StaleTranslation): string {
-  if (stale.was === undefined) return "the earlier text isn't recorded (the lock predates prosebook 0.2)";
-  return formatDiff(wordDiff(stale.was, stale.now)).replaceAll('\n', ' ');
-}
-
-function runTodo(config: ResolvedConfig, locale: string | undefined): number {
+function runTodo(config: ResolvedConfig, locale: string | undefined, prompt: boolean): number {
   if (locale === undefined) {
-    err('Usage: prosebook todo <locale>');
+    err('Usage: prosebook todo <locale> [--prompt]');
     return 1;
   }
   const { catalog, stale } = render(config);
-  const staleKeys = stale.get(locale) ?? new Map<string, StaleTranslation>();
-  const byArea = new Map<string, string[]>();
-  let count = 0;
-  for (const m of catalog.messages) {
-    const current = m.translations.get(locale);
-    if (current !== undefined && !staleKeys.has(m.key)) continue;
-    count += 1;
-    const lines = byArea.get(m.area) ?? [];
-    lines.push('');
-    if (m.context) lines.push(`# ${m.context}`);
-    for (const [arg, said] of m.argDocs) lines.push(`#   {${arg}}: ${said}`);
-    lines.push(`# ${config.source}: ${m.text.replaceAll('\n', ' ')}`);
-    const change = staleKeys.get(m.key);
-    if (change !== undefined) lines.push(`# stale, the source changed: ${changeOf(change)}`);
-    lines.push(stringify({ [m.key]: current?.text ?? '' }, { lineWidth: 0 }).trimEnd());
-    byArea.set(m.area, lines);
-  }
-  if (count === 0) {
-    out(`# ${locale} is complete`);
-    return 0;
+  const todo = todoOf(config, catalog, stale.get(locale) ?? new Map(), locale, prompt);
+  out(todo.text);
+  if (prompt && todo.count > 0) err(`\nHand this to a model, save its reply, and \`prosebook import ${locale} <reply>\`.`);
+  return 0;
+}
+
+function runImport(config: ResolvedConfig, locale: string | undefined, file: string | undefined): number {
+  if (locale === undefined || ((file === undefined || file === '-') && process.stdin.isTTY)) {
+    err('Usage: prosebook import <locale> <file>, or the reply on stdin');
+    return 1;
   }
-  out(
-    `# prosebook todo: ${count} entr${count === 1 ? 'y' : 'ies'} for ${locale}. Fill them in and paste each block into ${rel(config, config.locales)}/${locale}/<area>.yaml (or ${locale}.yaml).`,
-  );
-  for (const [area, lines] of byArea) {
-    out(`\n# ── ${area}.yaml ──`);
-    out(lines.join('\n'));
+  const reply = readFileSync(file === undefined || file === '-' ? 0 : resolve(file), 'utf8');
+  const { written, unchanged, problems } = importTranslations(config, locale, reply);
+  reportProblems(config, problems);
+  if (written.length + unchanged.length > 0) {
+    // A stale translation given back unchanged was looked at and still holds.
+    const stale = render(config).stale.get(locale) ?? new Map<string, StaleTranslation>();
+    const kept = unchanged.filter((key) => stale.has(key));
+    const { catalog } = generate(config, { accept: new Map([[locale, new Set(kept)]]) });
+    out(
+      `prosebook: imported ${written.length} translation(s) into ${locale}${kept.length > 0 ? `, and accepted ${kept.length} stale one(s) as still right` : ''}`,
+    );
+    const imported = new Set(written);
+    printFindings(
+      config,
+      lint(
+        catalog.messages.filter((m) => imported.has(m.key)),
+        config,
+      ).filter((f) => f.locale === locale),
+    );
   }
-  return 0;
+  if (problems.length === 0) return 0;
+  err(`\n${problems.length} left out: fix them, or hand these lines back to the model, and import again.`);
+  return 1;
 }
 
 function runScan(config: ResolvedConfig, strict: boolean, report?: SarifReport): number {

package/src/index.ts

@@ -6,7 +6,7 @@
  * functions: this runtime looks them up, picks the locale and falls back, and parses nothing.
  */
 export { createCopy, defineCatalog, type Catalog, type Copy, type CopyOptions } from './runtime/copy.ts';
-export { chainOf, negotiate, preferredLocales } from './runtime/locale.ts';
+export { acceptedLocales, chainOf, negotiate, preferredLocales } from './runtime/locale.ts';
 export { createHelpers, flatten } from './runtime/helpers.ts';
 export type {
   AnyTagFn,

package/src/inspector.ts

@@ -1,5 +1,5 @@
 /**
- * The dev inspector the Vite plugin loads into the page: hold Alt and point at a string to see its
+ * The dev inspector each integration loads into the page: hold Alt and point at a string to see its
  * key, Alt-click to open the entry it came from, Alt-Shift-click to open the catalog entry instead of
  * the translation. Alt-right-click edits the entry on the page instead (`inspector-dialog.ts`).
  *
@@ -113,10 +113,15 @@ export interface InspectorOptions {
   base: string;
 }
 
-/** Starts listening for reads and for Alt on the page. Called by the module the Vite plugin serves. */
+/**
+ * Starts listening for reads and for Alt on the page, once: Bun and Next call it from the generated
+ * index, which runs again whenever it changes.
+ */
 export function install({ base }: InspectorOptions): void {
+  const hooks = globalThis as DevHooks;
+  if (hooks.__PROSEBOOK_READ__ !== undefined) return;
   const reads: Reads = new Map();
-  (globalThis as DevHooks).__PROSEBOOK_READ__ = (key, text, locale) => record(reads, key, text, locale);
+  hooks.__PROSEBOOK_READ__ = (key, text, locale) => record(reads, key, text, locale);
 
   const box = document.createElement('div');
   const label = document.createElement('div');

package/src/next-loader.ts

@@ -0,0 +1,16 @@
+/**
+ * The Turbopack loader `prosebook/next` sets on the generated modules. In a build it hands over a
+ * locale module `withProsebook` has already pruned, since that reads the source once for every
+ * locale. In dev, in the browser, it puts what `withProsebook` hands it before the index (the hot
+ * hooks, and the inspector), and makes each locale module update the copies holding it whenever Fast
+ * Refresh runs it again.
+ */
+import { notifyingLocale } from './tools/bundle.ts';
+
+export type LoaderOptions = { code: string } | { prepend: string } | { locale: string };
+
+export default function loader(this: { getOptions(): LoaderOptions }, source: string): string {
+  const options = this.getOptions();
+  if ('code' in options) return options.code;
+  return 'prepend' in options ? options.prepend + source : notifyingLocale(source, options.locale);
+}

package/src/next.ts

@@ -0,0 +1,188 @@
+/**
+ * `prosebook/next`: the catalog as part of a Next.js app.
+ *
+ * Generates when `next dev` or `next build` loads the config, and in dev again whenever a catalog or
+ * translation file changes, so Fast Refresh picks up the new modules and a broken entry shows in the
+ * terminal. Server components read the new text on their next render; in the browser, each locale
+ * module hands its new messages to the copies holding it, which re-render in the locale and state
+ * they were in. `next build` ships only the messages the code names: each locale module is handed to a
+ * Turbopack loader (`next-loader.ts`) that returns it pruned. Turbopack loads a module before it has
+ * seen the code that reads it, so the keys come from the source under `scan.dirs` (`tools/bundle.ts`),
+ * read here once, and each pruned module travels to the loader as its options.
+ *
+ * In dev the browser's index also starts the inspector (`inspector.ts`). Its endpoints can't be a
+ * route of the app without a file in it, so a server of their own answers them on a local port, and a
+ * rewrite sends `/__prosebook/*` there; an entry opens through Next's own `/__nextjs_launch-editor`.
+ *
+ * Turbopack only: Next 16 fails a Turbopack build whose config has a `webpack` key, so none is added.
+ */
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { join, relative, resolve } from 'node:path';
+
+import type { LoaderOptions } from './next-loader.ts';
+import {
+  beside,
+  HOT_SET,
+  installInspector,
+  keeper,
+  prunedModule,
+  scanSources,
+  unseenMessage,
+  watchCatalog,
+  type Prune,
+} from './tools/bundle.ts';
+import { CatalogError } from './tools/catalog.ts';
+import { loadConfig, type ProsebookConfig, type ResolvedConfig } from './tools/config.ts';
+import { inspectorEndpoints, nodeMiddleware, redirect } from './tools/endpoints.ts';
+import { generate, type Generated } from './tools/generate.ts';
+
+export interface ProsebookNextOptions {
+  /** 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 Next app's when unset. */
+  root?: string;
+  /**
+   * 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[];
+  /** In dev, Alt-click a string on the page to open its entry in the editor. On by default. */
+  inspect?: boolean;
+}
+
+type Rules = { [glob: string]: unknown };
+type Rewrite = { source: string; destination: string };
+type Rewrites = Rewrite[] | { beforeFiles?: Rewrite[]; afterFiles?: Rewrite[]; fallback?: Rewrite[] };
+type ConfigFunction<C> = (phase: string, context: { defaultConfig: C }) => C | Promise<C>;
+
+const DEV = 'phase-development-server';
+const BUILD = 'phase-production-build';
+
+const loaderPath = beside(import.meta.url, 'next-loader');
+const inspectorPath = beside(import.meta.url, 'inspector');
+
+// Next loads its config more than once in a process; one watcher and one inspector server per catalog
+// is enough.
+const watching = new Set<string>();
+const serving = new Map<string, Promise<number>>();
+
+const describe = (e: unknown) => (e instanceof CatalogError ? e.message : e instanceof Error ? (e.stack ?? e.message) : String(e));
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Wraps the Next config: `export default withProsebook({ ... })`. Takes the config as an object or as
+ * the function Next calls with the phase, and returns the function.
+ */
+export function withProsebook<C extends object>(
+  next: C | ConfigFunction<C> = {} as C,
+  options: ProsebookNextOptions = {},
+): (phase: string, context: { defaultConfig: C }) => Promise<C> {
+  return async (phase, context) => {
+    const resolved = typeof next === 'function' ? await next(phase, context) : next;
+    if (phase !== DEV && phase !== BUILD) return resolved;
+    const config = await loadConfig(resolve(options.root ?? process.cwd()), options.config);
+    if (config.language === 'ts' && config.importExtension === '.js')
+      throw new Error("prosebook: Turbopack doesn't resolve `./en.js` to `en.ts`: set `importExtension: ''` in the prosebook config");
+    const generated = generate(config);
+    if (phase === DEV) {
+      watch(config);
+      if (options.inspect === false) return withRules(resolved, hotRules(config, generated, HOT_SET));
+      const base = `${(resolved as { basePath?: string }).basePath ?? ''}/`;
+      // A relative import, which Turbopack resolves as it would the app's own.
+      const path = relative(config.out, inspectorPath).replaceAll('\\', '/');
+      const prepend = HOT_SET + installInspector(path.startsWith('.') ? path : `./${path}`, base);
+      return withRewrite(withRules(resolved, hotRules(config, generated, prepend)), await serveInspector(config, base));
+    }
+    const prune = options.prune ?? 'strict';
+    if (prune === false) return resolved;
+    return withRules(resolved, prunedRules(config, generated, prune, options.keep));
+  };
+}
+
+function withRules<C extends object>(resolved: C, rules: Rules): C {
+  const turbopack = (resolved as { turbopack?: { rules?: Rules } }).turbopack;
+  return { ...resolved, turbopack: { ...turbopack, rules: { ...turbopack?.rules, ...rules } } };
+}
+
+/** Sends `/__prosebook/*` to the inspector's server, before any of the app's own rewrites. */
+function withRewrite<C extends object>(resolved: C, port: number): C {
+  const theirs = (resolved as { rewrites?: () => Promise<Rewrites> }).rewrites;
+  const ours = [{ source: '/__prosebook/:path*', destination: `http://127.0.0.1:${port}/__prosebook/:path*` }];
+  const rewrites = async (): Promise<Rewrites> => {
+    const r = (await theirs?.()) ?? [];
+    return Array.isArray(r) ? { beforeFiles: ours, afterFiles: r } : { ...r, beforeFiles: [...ours, ...(r.beforeFiles ?? [])] };
+  };
+  return { ...resolved, rewrites };
+}
+
+/**
+ * Serves the inspector's endpoints on a free local port, for as long as the process lives. Next's
+ * rewrite forwards the page's host, so an edit is still checked against the page's origin.
+ */
+function serveInspector(config: ResolvedConfig, base: string): Promise<number> {
+  let port = serving.get(config.catalog);
+  if (port !== undefined) return port;
+  const handle = inspectorEndpoints(config, {
+    open: ({ file, line, column }) =>
+      redirect(`${base}__nextjs_launch-editor?${new URLSearchParams({ file, line1: String(line), column1: String(column) })}`),
+  });
+  const middleware = nodeMiddleware(handle);
+  const server = createServer((req, res) =>
+    middleware(req, res, () => {
+      res.statusCode = 404;
+      res.end();
+    }),
+  );
+  port = new Promise<number>((done, fail) => {
+    server.once('error', fail);
+    server.listen(0, '127.0.0.1', () => done((server.address() as AddressInfo).port));
+  });
+  server.unref();
+  serving.set(config.catalog, port);
+  return port;
+}
+
+function watch(config: ResolvedConfig): void {
+  if (watching.has(config.catalog)) return;
+  watching.add(config.catalog);
+  watchCatalog(config, () => {
+    try {
+      generate(config);
+      console.info(`prosebook: regenerated ${relative(config.root, config.out).replaceAll('\\', '/')}`);
+    } catch (e) {
+      console.error(describe(e));
+    }
+  });
+}
+
+/**
+ * A rule per generated module: matched by its file name, then by its path, which Turbopack gives from
+ * its own root, so only the end is known.
+ */
+function rule(config: ResolvedConfig, name: string, options: LoaderOptions, browser = false): [string, unknown] {
+  const file = `${name}.${config.language === 'ts' ? 'ts' : 'js'}`;
+  const path = { path: new RegExp(`(?:^|/)${escape(join(relative(config.root, config.out), file).replaceAll('\\', '/'))}$`) };
+  return [file, { condition: browser ? { all: ['browser', path] } : path, loaders: [{ loader: loaderPath, options }] }];
+}
+
+/**
+ * In the browser: the index starts with `prepend`, the hot hooks and the inspector, there before any
+ * copy exists, and each locale updates the copies.
+ */
+function hotRules(config: ResolvedConfig, generated: Generated, prepend: string): Rules {
+  const locales = [...generated.entries.keys()].map((locale) => rule(config, locale, { locale }, true));
+  return Object.fromEntries([rule(config, 'index', { prepend }, true), ...locales]);
+}
+
+function prunedRules(config: ResolvedConfig, generated: Generated, prune: 'strict' | 'loose', keep?: string[]): Rules {
+  const { refs, unseen } = scanSources(config, prune === 'strict');
+  if (unseen.length > 0) throw new Error(unseenMessage(unseen, config.root));
+  const kept = keeper(refs, keep);
+  return Object.fromEntries([...generated.entries].map(([locale, entries]) => rule(config, locale, { code: prunedModule(entries, kept) })));
+}
+
+export default withProsebook;

package/src/react/index.tsx

@@ -14,23 +14,23 @@ type M = RegisteredMessages;
 type L = RegisteredLocale;
 
 /** `Copy`, with `rich` returning a `ReactNode`. */
-export interface ReactCopy extends Omit<Copy<M, L>, 'rich'> {
+export interface ReactCopy extends Omit<Copy, 'rich'> {
   rich<K extends RichKey<M>>(this: void, key: K, ...values: RichParam<M[K], ReactNode>): ReactNode;
 }
 
-const CopyContext = createContext<{ copy: Copy<M, L>; tags: Tags } | null>(null);
+const CopyContext = createContext<{ copy: Copy; tags: Tags } | null>(null);
 
 type Tags = { readonly [tag: string]: TagFn<ReactNode> };
 
 export interface CopyProviderProps {
-  copy: Copy<M, L> | Copy;
+  copy: Copy;
   /** Tag renderers every rich read under this provider gets, beside the copy's own. */
   tags?: Tags;
   children?: ReactNode;
 }
 
 export function CopyProvider({ copy, tags, children }: CopyProviderProps) {
-  const value = useMemo(() => ({ copy: copy as Copy<M, L>, tags: { ...(copy.tags as unknown as Tags), ...tags } }), [copy, tags]);
+  const value = useMemo(() => ({ copy: copy, tags: { ...(copy.tags as unknown as Tags), ...tags } }), [copy, tags]);
   return <CopyContext value={value}>{children}</CopyContext>;
 }
 
@@ -59,7 +59,7 @@ export function useLocale(): L {
 }
 
 // Takes the version only so the reader is rebuilt, and its identity changes, when what it reads does.
-function readerFor(copy: Copy<M, L>, tags: Tags, version: number): ReactCopy {
+function readerFor(copy: Copy, tags: Tags, version: number): ReactCopy {
   return {
     locale: copy.locale,
     version,
@@ -108,5 +108,5 @@ export type TextProps<K extends Extract<keyof M, string>> = { id: K } & ValuesPr
 export function Text<K extends Extract<keyof M, string>>(props: TextProps<K>) {
   const copy = useCopy();
   const values = (props as { values?: object }).values;
-  return <>{copy.rich(props.id as RichKey<M>, values)}</>;
+  return <>{copy.rich(props.id, values as never)}</>;
 }

package/src/react/server.ts

@@ -0,0 +1,37 @@
+/**
+ * `prosebook/react/server`: the catalog in React Server Components, which can't use context. Apart
+ * from `prosebook/react`, whose module makes a context as it loads, which the server build refuses.
+ */
+import { cache } from 'react';
+
+import { createCopy, type Catalog, type Copy, type CopyOptions } from '#src/runtime/copy.ts';
+import type { MessageShapes } from '#src/runtime/types.ts';
+
+/** What a request asks for: a locale, or the locales it prefers, most preferred first. */
+type Asked<L extends string> = L | (string & {}) | readonly string[];
+
+/**
+ * A reader of one copy per request, ready to use: `locale` is asked once per request, and every
+ * server component rendering in it gets the same copy, in the locale negotiated from the answer.
+ * React's `cache` keeps it per request, so one request's locale never reaches another's.
+ *
+ * ```ts
+ * 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];
+ * });
+ * const { t, locale } = await serverCopy();
+ * ```
+ */
+export function createServerCopy<M extends MessageShapes, L extends string>(
+  catalog: Catalog<M, L>,
+  locale: () => Asked<L> | Promise<Asked<L>>,
+  options: Omit<CopyOptions<L>, 'locale'> = {},
+): () => Promise<Copy<M, L>> {
+  return cache(async () => {
+    const copy = createCopy(catalog, { ...options, locale: await locale() });
+    await copy.ready;
+    return copy;
+  });
+}

package/src/runtime/copy.ts

@@ -43,6 +43,11 @@ export interface CopyOptions<L extends string> {
   tags?: { [tag: string]: AnyTagFn };
   /** What a key the catalog lacks reads as. Defaults to the key itself. */
   onMissing?: (key: string, locale: L) => string;
+  /**
+   * Told of a placeholder that had no value, or one `Intl` refused (`currency: 'euro'`): the message
+   * still renders, showing `{name}` there. Defaults to `console.error`.
+   */
+  onError?: (error: Error, key: string, locale: L) => void;
 }
 
 /** Its methods don't use `this`, so they can be passed around and destructured: `const { t } = copy`. */
@@ -92,9 +97,17 @@ export function createCopy<M extends MessageShapes, L extends string>(catalog: C
   const listeners = new Set<() => void>();
   const defaultTags = options.tags ?? {};
   const formatters = new Map<string, Intl.NumberFormat | Intl.DateTimeFormat | Intl.ListFormat | Intl.RelativeTimeFormat>();
+  // The key being rendered, which a helper's report names; none while the inspector renders it again.
+  let reading: string | undefined;
+  const helpers = (l: L) =>
+    createHelpers(l, (error) => {
+      if (reading === undefined) return;
+      if (options.onError) options.onError(error, reading, l);
+      else console.error(`prosebook: ${reading} in ${l}: ${error.message}`);
+    });
 
   for (const [locale, messages] of Object.entries(catalog.messages) as [L, CompiledMessages][])
-    loaded.set(locale, { messages, h: createHelpers(locale) });
+    loaded.set(locale, { messages, h: helpers(locale) });
 
   let locale = catalog.source;
   let chain: Layer[] = layers(chainOf(locale, catalog.locales, catalog.source));
@@ -127,7 +140,7 @@ export function createCopy<M extends MessageShapes, L extends string>(catalog: C
       const loader = catalog.loaders[l];
       if (loader === undefined) return Promise.reject(new Error(`prosebook: no messages for locale "${l}"`));
       p = loader().then((mod) => {
-        const layer = { messages: mod.default, h: createHelpers(l) };
+        const layer = { messages: mod.default, h: helpers(l) };
         loaded.set(l, layer);
         pending.delete(l);
         return layer;
@@ -163,7 +176,13 @@ export function createCopy<M extends MessageShapes, L extends string>(catalog: C
     const found = find(key);
     if (found === undefined) return options.onMissing ? options.onMissing(key, locale) : key;
     const [message, h] = found;
-    const out = typeof message === 'string' ? message : message(values, h);
+    reading = key;
+    let out: unknown;
+    try {
+      out = typeof message === 'string' ? message : message(values, h);
+    } finally {
+      reading = undefined;
+    }
     const read = (globalThis as DevHooks).__PROSEBOOK_READ__;
     if (read !== undefined) read(key, typeof out === 'string' ? out : textOf(message, values, h), h.locale);
     return out;