@saykit/format-json 0.4.0 → 0.5.0

package/README.md

@@ -70,10 +70,17 @@ 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.
 
+### Options
+
+- `dialect` (default none): `'arb'` or `'webextension'`, see above.
+- `includeReferences` (default `true`): include `x-saykit-references` source
+  references. No effect on the plain layout, which carries no metadata.
+- `includeLineNumbers` (default `true`): include line numbers in those references.
+
 > [!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.
+> get stable, human-readable keys. The plain layout carries no source
+> references, comments, or contexts — it is a lean runtime format.
 
 ## Documentation
 

package/dist/formatter.d.mts

@@ -1,5 +1,4 @@
 import { Formatter } from "@saykit/config";
-
 //#region src/formatter.d.ts
 type Dialect = 'arb' | 'webextension';
 interface FormatterOptions {
@@ -20,6 +19,18 @@ interface FormatterOptions {
    * metadata.
    */
   dialect?: Dialect;
+  /**
+   * Include source references in the generated catalogue. Only the metadata
+   * carrying dialects have anywhere to put them, so this has no effect on the
+   * plain layout.
+   * @default true
+   */
+  includeReferences?: boolean;
+  /**
+   * Include line numbers in source references.
+   * @default true
+   */
+  includeLineNumbers?: boolean;
 }
 declare function createJsonFormatter(options?: FormatterOptions): Formatter;
 //#endregion

package/dist/formatter.mjs

@@ -16,11 +16,16 @@ 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) {
+function toAttributes(message, options) {
 	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;
+	if (options.includeReferences !== false) {
+		let references = message.references ?? [];
+		if (options.includeLineNumbers === false) references = references.map((r) => r.replace(/:\d+$/, ""));
+		references = Array.from(new Set(references)).sort();
+		if (references.length) attributes[REFERENCES_FIELD] = references;
+	}
 	return attributes;
 }
 /** Reconstruct a {@link Message} from a key, its value, and optional metadata. */
@@ -56,7 +61,7 @@ function createJsonFormatter(options = {}) {
 				for (const message of sorted) {
 					const key = messageKey(message);
 					catalogue[key] = message.translation ?? "";
-					const attributes = toAttributes(message);
+					const attributes = toAttributes(message, options);
 					if (Object.keys(attributes).length) catalogue[`@${key}`] = attributes;
 				}
 				return `${JSON.stringify(catalogue, null, 2)}\n`;
@@ -65,7 +70,7 @@ function createJsonFormatter(options = {}) {
 				const catalogue = {};
 				for (const message of sorted) catalogue[messageKey(message)] = {
 					message: message.translation ?? "",
-					...toAttributes(message)
+					...toAttributes(message, options)
 				};
 				return `${JSON.stringify(catalogue, null, 2)}\n`;
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/format-json",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "JSON file formatter for saykit",
   "keywords": [
     "formatter",
@@ -34,7 +34,7 @@
     "provenance": true
   },
   "devDependencies": {
-    "@saykit/config": "^0.4.0"
+    "@saykit/config": "^0.5.0"
   },
   "peerDependencies": {
     "@saykit/config": "*"