@l10nmonster/helpers-json 1.0.0 → 1.0.3

package/README.md

@@ -2,12 +2,13 @@
 
 ### JSON Filter
 
-A filter for JSON files. It supports annotations as defined by the [ARB spec](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification). In addition it supports nested keys and plurals as defined by the [i18next JSON v4](https://www.i18next.com/misc/json-format) format.
+A filter for JSON files. It supports annotations as defined by the [ARB spec](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification). In addition it supports arrays, nested keys and plurals as defined by the [i18next JSON v4](https://www.i18next.com/misc/json-format) format.
 
 ```js
 this.resourceFilter = new filters.JsonFilter({
         enableArbAnnotations: true,
         enablePluralSuffixes: true,
-        emitArbAnnotations: true
+        emitArbAnnotations: true,
+        enableArrays: true
 });
 ```

package/i18next.js

@@ -1,40 +1,69 @@
+// Intentionally uses `== null` to handle undefined and null
+/* eslint-disable no-eq-null, eqeqeq */
+
 // i18next v4 json format defined at https://www.i18next.com/misc/json-format
 const flat = require('flat');
 const { regex } = require('@l10nmonster/helpers');
+const { flattenAndSplitResources, ARB_ANNOTATION_MARKER, arbPlaceholderHandler } = require('./utils');
 
-const isArbAnnotations = e => e[0].split('.').slice(-2)[0].startsWith('@');
-const validArbAnnotations = new Set(['description', 'type', 'context', 'placeholders', 'screenshot', 'video', 'source_text']);
+const isArbAnnotations = e => e[0].split('.').slice(-2)[0].startsWith(ARB_ANNOTATION_MARKER);
 const validPluralSuffixes = new Set(['one', 'other', 'zero', 'two', 'few', 'many']);
 const extractArbGroupsRegex = /(?<prefix>.+?\.)?@(?<key>\S+)\.(?<attribute>\S+)/;
+const defaultArbAnnotationHandlers = {
+    description: (_, data) => (data == null ? undefined : data),
+    placeholders: (_, data) => (data == null ? undefined : arbPlaceholderHandler(data)),
+    DEFAULT: (name, data) => (data == null ? undefined : `${name}: ${data}`),
+}
+
+function parseResourceAnnotations(resource, enableArbAnnotations, arbAnnotationHandlers) {
+    if (!enableArbAnnotations) {
+        return [ Object.entries(flat.flatten(resource)), {} ]
+    }
 
-function parseResourceAnnotations(resource, enableArbAnnotations) {
-    let parsedResource = Object.entries(flat.flatten(resource));
-    const notes = {};
-    if (enableArbAnnotations) {
-        for (const [key, value] of parsedResource.filter(isArbAnnotations)) {
-            const arbGroups = extractArbGroupsRegex.exec(key).groups;
-            const sid = `${arbGroups.prefix ?? ''}${arbGroups.key}`;
-            if (validArbAnnotations.has(arbGroups.attribute)) {
-                notes[sid] = `${notes[sid] ? `${notes[sid]}\n` : ''}${arbGroups.attribute === 'description' ? '' : `${arbGroups.attribute}: `}${arbGroups.attribute === 'placeholders' ? JSON.stringify(value) : value}`;
-            } else {
-                l10nmonster.logger.verbose(`Unexpected ${arbGroups.attribute} annotation for SID ${sid}`);
+    const { res, notes } = flattenAndSplitResources([], resource)
+    const parsedNotes = {}
+    for (const [key, arbAnnotations] of Object.entries(notes)) {
+        if (typeof arbAnnotations === "object") {
+            const notes = []
+            for (const [annotation, data] of Object.entries(arbAnnotations)) {
+                const handler = arbAnnotationHandlers[annotation] ?? arbAnnotationHandlers.DEFAULT
+                if (handler != null) {
+                    const val = handler(annotation, data)
+                    if (val !== undefined) {
+                        notes.push(val)
+                    }
+                }
             }
+            parsedNotes[key] = notes.join("\n")
+        } else {
+            parsedNotes[key] = arbAnnotations
         }
     }
-    enableArbAnnotations && (parsedResource = parsedResource.filter(e => !isArbAnnotations(e)));
-    return [ parsedResource, notes ];
+    return [ Object.entries(res), parsedNotes ];
 }
 
 exports.Filter = class I18nextFilter {
     constructor(params) {
         this.enableArbAnnotations = params?.enableArbAnnotations || false;
         this.enablePluralSuffixes = params?.enablePluralSuffixes || false;
+        this.enableArrays = params?.enableArrays || false;
         this.emitArbAnnotations = params?.emitArbAnnotations || false;
+        this.arbAnnotationHandlers = {
+            ...defaultArbAnnotationHandlers,
+            ...(params?.arbAnnotationHandlers ?? {})
+        }
     }
 
     async parseResource({ resource }) {
         const segments = [];
-        const [ parsedResource, notes ] = parseResourceAnnotations(JSON.parse(resource), this.enableArbAnnotations);
+        if (!resource) {
+            return { segments };
+        }
+        const [ parsedResource, notes ] = parseResourceAnnotations(
+            JSON.parse(resource),
+            this.enableArbAnnotations,
+            this.arbAnnotationHandlers,
+        );
         for (const [key, value] of parsedResource) {
             let seg = { sid: key, str: value };
             notes[key] && (seg.notes = notes[key]);
@@ -70,7 +99,7 @@ exports.Filter = class I18nextFilter {
                 }
             }
         }
-        return JSON.stringify(flat.unflatten(flatResource), null, 2);
+        return JSON.stringify(flat.unflatten(flatResource, { object: !this.enableArrays }), null, 2) + '\n';
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@l10nmonster/helpers-json",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Helpers to deal with JSON file formats",
   "main": "index.js",
   "scripts": {

package/utils.js

@@ -0,0 +1,114 @@
+const ARB_ANNOTATION_MARKER = "@";
+const FLATTEN_SEPARATOR = ".";
+
+/**
+ * Recursively flatten the resources object while splitting it into resources and notes
+ * Keys that start with the ARB annotation marker are separated into notes
+ *
+ * @param {string[]} keys Stack of keys seen. Used to create a flattened key
+ * @param {object} resource Object to parse
+ * @returns {{resource: object, notes: object}}
+ *
+ * ```
+ * const obj = {
+ *   str: "string",
+ *   "@str": {
+ *     description: "string",
+ *   },
+ *   ns1: {
+ *     str: "string, {{foo}}",
+ *     "@str": {
+ *       description: "string",
+ *       placeholders: { foo: { example: "foo example", description: "foo description" } }
+ *     },
+ *     ns2: {
+ *       str: "string",
+ *       "@str": {
+ *         description: "string",
+ *       },
+ *     }
+ *   }
+ * }
+ * const {res, notes} = flattenAndSplitResources([], obj)
+ * assert(
+ *   JSON.stringify(res) === JSON.stringify({
+ *     str: 'string',
+ *     'ns1.str': 'string, {{foo}}',
+ *     'ns1.ns2.str': 'string'
+ *   })
+ * )
+ * assert(
+ *   JSON.stringify(notes) === JSON.stringify({
+ *     str: {
+ *       description: 'string'
+ *     },
+ *     'ns1.str': {
+ *       description: 'string',
+ *       placeholders: {
+ *         foo: {
+ *           example: "foo example",
+ *           description: "foo description"
+ *         }
+ *       }
+ *     },
+ *     'ns1.ns2.str': {
+ *       description: 'string'
+ *     }
+ *   })
+ * )
+ * ```
+ */
+function flattenAndSplitResources(keys, obj) {
+    return Object.entries(obj).reduce((acc, [key, value]) => {
+        if (typeof value === "object" && key.startsWith(ARB_ANNOTATION_MARKER)) {
+            // If the key is `@key` and the value is an object, it is likely an ARB annotation.
+            // Put it in the `notes` object.
+            const k = keys.slice().concat(key.slice(1))
+            acc.notes[k.join(FLATTEN_SEPARATOR)] = value
+        } else if (typeof value === "object") {
+            // If the key is _not_ `@key` and the value is an object, it is a namespace.
+            // Recursively flatten and split the value.
+            const { res, notes } = flattenAndSplitResources([...keys, key], value)
+            Object.assign(acc.res, res)
+            Object.assign(acc.notes, notes)
+        } else {
+            // If the value is _not_ an object, it is a key-value pair of resources.
+            // Put it in the `res` object.
+            const k = keys.concat(key)
+            acc.res[k.join(FLATTEN_SEPARATOR)] = value
+        }
+        return acc
+  }, { res: {}, notes: {} })
+}
+
+/**
+ * Accepts ARB placeholders and returns them in PH() format
+ *
+ * ```
+ * const placeholders = {
+ *   count: {
+ *     example: "1",
+ *     description: "number of tickets"
+ *   }
+ * }
+ * const ph = arbPlaceholderHandler(placeholders)
+ * assert(ph === "PH({{count}}|1|number of tickets)")
+ * ```
+ *
+ * @param {{ [key: string]: value }} ARB placeholders
+ * @returns {string} placeholders formatted in PH() and separated by "\n"
+ */
+function arbPlaceholderHandler(placeholders) {
+    const phs = []
+    for (const [key, val] of Object.entries(placeholders)) {
+        phs.push(`PH({{${key}}}|${val.example}|${val.description})`)
+    }
+    return phs.join("\n")
+}
+
+module.exports = {
+    ARB_ANNOTATION_MARKER,
+    FLATTEN_SEPARATOR,
+    flattenAndSplitResources,
+    arbPlaceholderHandler,
+}