P7: compile messages to data, not to functions

.changeset/lucky-moons-shave.md

@@ -0,0 +1,9 @@
+---
+'saykit': minor
+'@saykit/config': minor
+'@saykit/react': minor
+'babel-plugin-saykit': minor
+'unplugin-saykit': minor
+---
+
+Compile catalogues to data modules with `saykit compile`, and drop the runtime message parser

.gitignore

@@ -3,4 +3,8 @@ node_modules/
 .turbo/
 .coverage/
 dist/
-RELEASE_NOTES.md
+RELEASE_NOTES.md
+# Locale modules the saykit CLI compiles from the catalogues beside them.
+# Their declarations are committed, so `tsc` passes before anything is generated.
+examples/**/locales/*.js
+examples/**/_locales/**/*.js

README.md

@@ -33,7 +33,7 @@ This is a pnpm monorepo. The published packages live in [`packages/*`](./package
 
 | Package                                             | Description                                                          |
 | --------------------------------------------------- | -------------------------------------------------------------------- |
-| [`saykit`](./packages/integration)                  | Core runtime: catalogues, views, macros, and ICU formatting          |
+| [`saykit`](./packages/integration)                  | Core runtime: catalogues, views, macros, and `Intl` helpers          |
 | [`@saykit/config`](./packages/config)               | Config schema (`defineConfig`) and the `saykit` CLI                  |
 | [`@saykit/react`](./packages/integration-react)     | React integration: `<Say>`, `SayProvider`, server helpers            |
 | [`@saykit/carbon`](./packages/integration-carbon)   | Carbon Discord-bot integration                                       |

examples/babel/README.md

@@ -3,10 +3,10 @@
 SayKit compiled by **Babel and nothing else**: no bundler, no dev server, no loader.
 `pnpm build`, then `node dist/main.js`.
 
-This exists to pin down the `catalogues: 'inline'` default: `babel-plugin-saykit` on its
-own has to rewrite the macros _and_ resolve the catalogue imports, with no other tool
-involved. Every other example runs the plugin alongside a bundler integration, so this is
-the only one that would notice if that stopped being true.
+This exists to pin down what `babel-plugin-saykit` does on its own: rewrite the macros,
+and nothing else. Catalogues are compiled to `.js` modules by `saykit compile`, which Node
+imports directly. Every other example runs the plugin alongside a bundler, so this is the
+only one that would notice if the plugin started needing one.
 
 ## Run
 
@@ -31,18 +31,15 @@ English source string, merged in at compile time rather than looked up at runtim
 
 ## What to look at
 
-| Thing                                                             | Where             |
-| ----------------------------------------------------------------- | ----------------- |
-| `plugins: ['saykit']`, no options: the inlining default           | `babel.config.js` |
-| `import en from './locales/en.po'`, gone by the time Node sees it | `src/main.ts`     |
-| The compiled record, one object literal per locale                | `dist/main.js`    |
+| Thing                                                  | Where               |
+| ------------------------------------------------------ | ------------------- |
+| `plugins: ['saykit']`, no options and nothing else     | `babel.config.js`   |
+| `import en from './locales/en.js'`, an ordinary import | `src/main.ts`       |
+| One readable function per message                      | `src/locales/fr.js` |
 
-Open `dist/main.js` after a build: there is no `.po` file, no PO parser and no SayKit
-extractor in the output, just `const en = { … }` and `say.call()` invocations.
+Open `dist/main.js` after a build: no `.po` file, no PO parser, no message parser and no
+SayKit extractor, just `say.call()` invocations against the imported locale modules.
 
-## Hot reload
-
-There is none, by design. The record lands inside `dist/main.js`, whose own bytes only
-change when you rebuild, which is exactly why a dev server wants `catalogues: 'module'`
-and a bundler integration instead. See the
+Open `src/locales/fr.js` to see what those modules hold: one plain function per message,
+with the locale and every number and date format already resolved. See the
 [Babel integration docs](../../website/content/integrations/babel.mdx).

examples/babel/package.json

@@ -4,8 +4,12 @@
   "scripts": {
     "check": "tsc --noEmit",
     "extract": "saykit extract",
-    "build": "babel src --extensions .ts --out-dir dist --ignore \"src/**/*.d.po.ts\"",
-    "start": "pnpm build && node dist/main.js"
+    "build": "babel src --extensions .ts,.js --out-dir dist --ignore \"src/**/*.d.ts\"",
+    "start": "pnpm build && node dist/main.js",
+    "compile": "saykit compile",
+    "prebuild": "saykit compile",
+    "precheck": "saykit compile",
+    "prestart": "saykit compile"
   },
   "dependencies": {
     "saykit": "workspace:^"

examples/babel/src/locales/en.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/babel/src/locales/fr.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/babel/src/main.ts

@@ -1,6 +1,6 @@
 import { createCatalogue } from 'saykit';
-import en from './locales/en.po';
-import fr from './locales/fr.po';
+import en from './locales/en.js';
+import fr from './locales/fr.js';
 
 const catalogue = createCatalogue({ en, fr });
 

examples/browser-extension/_locales/de/messages.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/browser-extension/_locales/en/messages.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/browser-extension/_locales/fr/messages.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/browser-extension/package.json

@@ -6,7 +6,11 @@
     "check": "tsc --noEmit",
     "extract": "saykit extract",
     "build": "vite build",
-    "dev": "vite build --watch"
+    "dev": "vite build --watch",
+    "compile": "saykit compile",
+    "predev": "saykit compile",
+    "prebuild": "saykit compile",
+    "precheck": "saykit compile"
   },
   "dependencies": {
     "saykit": "workspace:^"

examples/browser-extension/src/i18n.ts

@@ -1,7 +1,7 @@
 import { createCatalogue } from 'saykit';
-import de from '../_locales/de/messages.json';
-import en from '../_locales/en/messages.json';
-import fr from '../_locales/fr/messages.json';
+import de from '../_locales/de/messages.js';
+import en from '../_locales/en/messages.js';
+import fr from '../_locales/fr/messages.js';
 
 export const locales = ['en', 'fr', 'de'] as const;
 export type Locale = (typeof locales)[number];

examples/carbon/package.json

@@ -6,7 +6,11 @@
     "check": "tsc --noEmit",
     "extract": "saykit extract",
     "build": "tsdown",
-    "dev": "wrangler dev"
+    "dev": "wrangler dev",
+    "compile": "saykit compile",
+    "predev": "saykit compile",
+    "prebuild": "saykit compile",
+    "precheck": "saykit compile"
   },
   "dependencies": {
     "@buape/carbon": "0.16.0",

examples/carbon/src/i18n.ts

@@ -1,9 +1,9 @@
 import { createWithSay } from '@saykit/carbon';
 import { createCatalogue } from 'saykit';
-import de from './locales/de.json';
-import en from './locales/en-US.json';
-import fr from './locales/fr.json';
-import ja from './locales/ja.json';
+import de from './locales/de.js';
+import en from './locales/en-US.js';
+import fr from './locales/fr.js';
+import ja from './locales/ja.js';
 
 export const locales = ['en-US', 'fr', 'de', 'ja'] as const;
 export type Locale = (typeof locales)[number];

examples/carbon/src/locales/de.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/carbon/src/locales/en-US.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/carbon/src/locales/fr.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/carbon/src/locales/ja.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/custom-formatter/package.json

@@ -6,7 +6,11 @@
     "check": "tsc --noEmit",
     "extract": "saykit extract",
     "build": "tsdown",
-    "start": "node dist/main.mjs"
+    "start": "node dist/main.mjs",
+    "compile": "saykit compile",
+    "prebuild": "saykit compile",
+    "precheck": "saykit compile",
+    "prestart": "saykit compile"
   },
   "dependencies": {
     "saykit": "workspace:^",

examples/custom-formatter/src/i18n.ts

@@ -1,7 +1,7 @@
 import { createCatalogue } from 'saykit';
-import de from './locales/de.yml';
-import en from './locales/en.yml';
-import fr from './locales/fr.yml';
+import de from './locales/de.js';
+import en from './locales/en.js';
+import fr from './locales/fr.js';
 
 export const locales = ['en', 'fr', 'de'] as const;
 export type Locale = (typeof locales)[number];

examples/custom-formatter/src/locales/de.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/custom-formatter/src/locales/en.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/custom-formatter/src/locales/fr.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/expo/README.md

@@ -42,7 +42,7 @@ would otherwise produce loose strings between elements.
 
 Metro is not a Vite/Rollup-family bundler, so `unplugin-saykit` does not apply. Metro compiles every
 module through Babel, and `babel-plugin-saykit` hooks in there instead, doing the same two jobs:
-rewriting the macros, and inlining `import en from './locales/en.json'` as a plain object.
+rewriting the macros, and inlining `import en from './locales/en.js'` as a plain object.
 
 ```js
 module.exports = function babelConfig(api) {

examples/expo/babel.config.js

@@ -3,6 +3,6 @@ module.exports = function babelConfig(api) {
 
   return {
     presets: ['babel-preset-expo'],
-    plugins: [['saykit', { catalogues: 'module' }]],
+    plugins: ['saykit'],
   };
 };

examples/expo/metro.config.js

@@ -1,8 +1,7 @@
 const path = require('node:path');
 const { getDefaultConfig } = require('expo/metro-config');
-const { withSayKit } = require('babel-plugin-saykit/metro');
 
-const config = withSayKit(getDefaultConfig(__dirname));
+const config = getDefaultConfig(__dirname);
 
 // Two copies of React break hooks, so force every request to this app's copy
 config.resolver.resolveRequest = (context, moduleName, platform) => {

examples/expo/package.json

@@ -5,7 +5,10 @@
   "scripts": {
     "check": "tsc --noEmit",
     "extract": "saykit extract",
-    "dev": "expo start"
+    "dev": "expo start",
+    "compile": "saykit compile",
+    "predev": "saykit compile",
+    "precheck": "saykit compile"
   },
   "dependencies": {
     "@formatjs/intl-getcanonicallocales": "^3.2.11",

examples/expo/src/i18n.ts

@@ -1,8 +1,8 @@
 import { getLocales } from 'expo-localization';
 import { createCatalogue, createStore } from 'saykit';
-import en from './locales/en.json';
-import fr from './locales/fr.json';
-import ja from './locales/ja.json';
+import en from './locales/en.js';
+import fr from './locales/fr.js';
+import ja from './locales/ja.js';
 
 export const locales = ['en', 'fr', 'ja'] as const;
 export type Locale = (typeof locales)[number];

examples/expo/src/locales/en.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/expo/src/locales/fr.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/expo/src/locales/ja.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from 'saykit';
+
+declare const messages: Record<string, Message>;
+export default messages;

examples/nextjs/README.md

@@ -37,9 +37,10 @@ The component you write is identical in both cases:
 </Say>
 ```
 
-Because both halves are fed from the same view, with the client provider
-reading its locale and messages straight off it, server output and client hydration cannot disagree
-about which locale is active.
+Because both halves are fed from the same view, with the client provider reading its locale and
+messages straight off it, server output and client hydration cannot disagree about which locale is
+active. Messages compile to data rather than to functions, so they cross the boundary as the JSON
+they already are.
 
 ## Why `src/config.ts` exists separately
 
@@ -56,7 +57,7 @@ Next.js compiles with its own toolchain, so the macros are rewritten by `babel-p
 { "presets": ["next/babel"], "plugins": ["saykit"] }
 ```
 
-The plugin also rewrites `import en from './locales/en.po'` into an inline object. It requires a
+The plugin also rewrites `import en from './locales/en.js'` into an inline object. It requires a
 **default** import for catalogue files and throws on a named one, which is the intended failure
 mode, not a bug.
 

examples/nextjs/next.config.mjs

@@ -1,3 +1,2 @@
-import { withSayKit } from 'babel-plugin-saykit/next';
-
-export default withSayKit({});
+/** @type {import('next').NextConfig} */
+export default {};

examples/nextjs/package.json

@@ -7,7 +7,12 @@
     "extract": "saykit extract",
     "dev": "next dev",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "compile": "saykit compile",
+    "predev": "saykit compile",
+    "prebuild": "saykit compile",
+    "precheck": "saykit compile",
+    "prestart": "saykit compile"
   },
   "dependencies": {
     "@saykit/react": "workspace:^",

examples/nextjs/src/i18n.ts

@@ -1,8 +1,8 @@
 import { createWithSay } from '@saykit/react/server';
 import { createCatalogue } from 'saykit';
-import en from './locales/en.po';
-import fr from './locales/fr.po';
-import pl from './locales/pl.po';
+import en from './locales/en.js';
+import fr from './locales/fr.js';
+import pl from './locales/pl.js';
 
 export const catalogue = createCatalogue({ en, fr, pl });