@saykit/format-json 0.0.0 → 0.3.0

package/README.md

@@ -0,0 +1,80 @@
+# @saykit/format-json
+
+> JSON file formatter for [SayKit](https://saykit.js.org).
+
+[![Coverage](https://codecov.io/gh/k0d13/saykit/graph/badge.svg?flag=format-json)](https://codecov.io/gh/k0d13/saykit?flags%5B0%5D=format-json)
+
+Writes one JSON catalogue per locale — the de facto format for web i18n
+(react-intl, FormatJS, i18next, …). Reach for this instead of
+[`@saykit/format-po`](https://github.com/k0d13/saykit/tree/main/packages/format-po)
+when you want plain JSON bundles with no Gettext tooling.
+
+## Install
+
+```sh
+pnpm add -D @saykit/format-json
+```
+
+## Usage
+
+```ts title="saykit.config.ts"
+import json from '@saykit/format-json';
+
+// inside a bucket:
+formatter: json();
+```
+
+Each catalogue is a pretty-printed, flat map keyed by the message id (falling
+back to a stable content hash when a message has no id — the same key the
+runtime resolves), with the translation as the value:
+
+```json
+{
+  "greeting": "Hello"
+}
+```
+
+ICU MessageFormat strings are stored verbatim as JSON string values — JSON
+escaping is handled for you.
+
+### Dialects
+
+The plain layout above is just `{ key: value }`, so it drops comments, context,
+and source references. Pass `dialect` to keep them using a richer — but still
+standard — JSON layout:
+
+- `dialect: 'arb'` — [Application Resource Bundle](https://github.com/google/app-resource-bundle)
+  (Flutter/Dart `intl`). Strings stay flat; each key's metadata lives in a
+  sibling `@key` object.
+- `dialect: 'webextension'` — the Chrome/WebExtension `messages.json` shape,
+  where each key maps to a `{ message, description }` object.
+
+```ts
+formatter: json({ dialect: 'arb' });
+```
+
+```json title="ARB"
+{
+  "@@locale": "fr",
+  "greeting": "Bonjour",
+  "@greeting": {
+    "description": "A friendly hello",
+    "x-saykit-context": "formal",
+    "x-saykit-references": ["src/app.ts:10"]
+  }
+}
+```
+
+Both formats carry translator comments in their native `description` field.
+Context and source references have no standard slot, so SayKit round-trips them
+through `x-saykit-context` / `x-saykit-references` extension fields — other
+tooling reads the `description` and safely ignores the rest.
+
+> [!NOTE]
+> JSON catalogues are keyed by message id, so give your messages explicit ids to
+> get stable, human-readable keys. Unlike the PO formatter, JSON does not carry
+> source references, comments, or contexts — it is a lean runtime format.
+
+## Documentation
+
+See [saykit.js.org/core-concepts/formats](https://saykit.js.org/core-concepts/formats).

package/dist/formatter.d.mts

@@ -0,0 +1,26 @@
+import { Formatter } from "@saykit/config";
+
+//#region src/formatter.d.ts
+type Dialect = 'arb' | 'webextension';
+interface FormatterOptions {
+  /**
+   * The JSON dialect to write. A dialect other than the default plain
+   * `{ key: value }` map carries message metadata (comments, context, source
+   * references) using a richer — but still standard — layout.
+   *
+   * - `'arb'` — Application Resource Bundle (Flutter/Dart `intl`). Strings stay
+   *   flat and each key's metadata lives in a sibling `@key` object.
+   * - `'webextension'` — the Chrome/WebExtension `messages.json` shape, where
+   *   each key maps to a `{ message, description }` object.
+   *
+   * Both carry translator comments in their native `description` field. Context
+   * and source references have no standard slot, so they round-trip through
+   * `x-saykit-context` / `x-saykit-references` extension fields that other
+   * tooling safely ignores. Omit for a plain flat catalogue, which carries no
+   * metadata.
+   */
+  dialect?: Dialect;
+}
+declare function createJsonFormatter(options?: FormatterOptions): Formatter;
+//#endregion
+export { type Dialect, type FormatterOptions, createJsonFormatter as default };

package/dist/formatter.mjs

@@ -0,0 +1,79 @@
+import { generateHash } from "@saykit/config/features/messages";
+//#region src/formatter.ts
+/**
+* Derive a catalogue key the same way the runtime and the rest of SayKit do:
+* an explicit id when present, otherwise a stable hash of the message and its
+* context. Keying by the raw message text instead would not match the hashed
+* key the runtime looks up, and would collide for same-text/different-context
+* messages.
+*/
+function messageKey(message) {
+	return message.id ?? generateHash(message.message, message.context);
+}
+const CONTEXT_FIELD = "x-saykit-context";
+const REFERENCES_FIELD = "x-saykit-references";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Build the metadata attributes shared by the ARB and WebExtension layouts. */
+function toAttributes(message) {
+	const attributes = {};
+	if (message.comments.length) attributes.description = message.comments.join("\n");
+	if (message.context) attributes[CONTEXT_FIELD] = message.context;
+	if (message.references.length) attributes[REFERENCES_FIELD] = message.references;
+	return attributes;
+}
+/** Reconstruct a {@link Message} from a key, its value, and optional metadata. */
+function toMessage(key, value, attributes) {
+	const description = attributes && typeof attributes.description === "string" ? attributes.description : "";
+	const context = attributes && typeof attributes[CONTEXT_FIELD] === "string" ? attributes[CONTEXT_FIELD] : void 0;
+	const references = attributes && Array.isArray(attributes[REFERENCES_FIELD]) ? attributes[REFERENCES_FIELD].filter((r) => typeof r === "string") : [];
+	return {
+		id: key,
+		message: value,
+		translation: value,
+		context,
+		comments: description ? description.split("\n") : [],
+		references
+	};
+}
+function createJsonFormatter(options = {}) {
+	return {
+		extension: ".json",
+		parse(content) {
+			const data = JSON.parse(content);
+			if (options.dialect === "arb") return Object.entries(data).filter(([key, value]) => !key.startsWith("@") && typeof value === "string").map(([key, value]) => toMessage(key, value, data[`@${key}`]));
+			if (options.dialect === "webextension") return Object.entries(data).filter(([, value]) => isRecord(value) && typeof value.message === "string").map(([key, value]) => {
+				const entry = value;
+				return toMessage(key, entry.message, entry);
+			});
+			return Object.entries(data).filter(([, value]) => typeof value === "string").map(([key, value]) => toMessage(key, value));
+		},
+		stringify(messages, { locale }) {
+			const sorted = [...messages].sort((a, b) => messageKey(a).localeCompare(messageKey(b)));
+			if (options.dialect === "arb") {
+				const catalogue = { "@@locale": locale };
+				for (const message of sorted) {
+					const key = messageKey(message);
+					catalogue[key] = message.translation ?? "";
+					const attributes = toAttributes(message);
+					if (Object.keys(attributes).length) catalogue[`@${key}`] = attributes;
+				}
+				return `${JSON.stringify(catalogue, null, 2)}\n`;
+			}
+			if (options.dialect === "webextension") {
+				const catalogue = {};
+				for (const message of sorted) catalogue[messageKey(message)] = {
+					message: message.translation ?? "",
+					...toAttributes(message)
+				};
+				return `${JSON.stringify(catalogue, null, 2)}\n`;
+			}
+			const catalogue = {};
+			for (const message of sorted) catalogue[messageKey(message)] = message.translation ?? "";
+			return `${JSON.stringify(catalogue, null, 2)}\n`;
+		}
+	};
+}
+//#endregion
+export { createJsonFormatter as default };

package/package.json

@@ -1,4 +1,46 @@
-{
-  "name": "@saykit/format-json",
-  "version": "0.0.0"
+{
+  "name": "@saykit/format-json",
+  "version": "0.3.0",
+  "description": "JSON file formatter for saykit",
+  "keywords": [
+    "formatter",
+    "i18n",
+    "json",
+    "saykit"
+  ],
+  "homepage": "https://github.com/k0d13/saykit#readme",
+  "bugs": {
+    "url": "https://github.com/k0d13/saykit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k0d13/saykit.git",
+    "directory": "packages/format-json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/formatter.d.mts",
+      "default": "./dist/formatter.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@saykit/config": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@saykit/config": "*"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsdown"
+  }
 }