@l10nmonster/helpers-json 3.0.0-alpha.16 → 3.0.0-alpha.17

package/i18next.js

@@ -2,13 +2,16 @@
 /* eslint-disable no-eq-null, eqeqeq */
 
 // i18next v4 json format defined at https://www.i18next.com/misc/json-format
-import { flatten, unflatten } from 'flat';
+import { unflatten } from 'flat';
 import { regex } from '@l10nmonster/core';
-import { flattenAndSplitResources, ARB_ANNOTATION_MARKER, arbPlaceholderHandler } from './utils.js';
+import {
+    arbPlaceholderHandler,
+    parseResourceAnnotations,
+} from './utils.js';
+
+const ALL_PLURAL_FORMS = ['zero', 'one', 'two', 'few', 'many', 'other'];
+const DEFAULT_SOURCE_PLURAL_FORMS = ['one', 'other'];
 
-const isArbAnnotations = e => e[0].split('.').some(segment => segment.startsWith(ARB_ANNOTATION_MARKER));
-const validPluralSuffixes = new Set(['one', 'other', 'zero', 'two', 'few', 'many']);
-const extractArbGroupsRegex = /(?<prefix>.+?\.)?@(?<key>[^.]+)\.(?<attribute>.+)/;
 const defaultArbAnnotationHandlers = {
     description: (_, data) => (data == null ? undefined : data),
     placeholders: (_, data) => (data == null ? undefined : arbPlaceholderHandler(data)),
@@ -16,139 +19,122 @@ const defaultArbAnnotationHandlers = {
 }
 
 /**
- * @function parseResourceAnnotations
- *
- * @description
- * Parse resource annotations according to the given configuration.
- *
- * @param {object} resource - The resource to parse.
- * @param {boolean} enableArbAnnotations - Whether to enable annotations
- * @param {object} arbAnnotationHandlers - An object mapping annotation names to a function which takes an annotation name and its value and returns a string.
- *
- * @returns {array} An array with two elements. The first element is an array of key-value pairs for the translatable segments. The second element is an object with the parsed annotations.
- *
- * @example
- * const resource = {
- *   "key": "value",
- *   "@key": {
- *     "description": "description for key",
- *     "placeholders": {
- *       "placeholder": {
- *         "example": "example for placeholder",
- *         "description": "description for placeholder",
- *       }
- *     }
- *   }
- * };
- * const [segments, notes] = parseResourceAnnotations(resource, true, {
- *   description: (_, data) => (data == null ? undefined : data),
- *   placeholders: (_, data) => (data == null ? undefined : arbPlaceholderHandler(data)),
- *   DEFAULT: (name, data) => (data == null ? undefined : `${name}: ${data}`),
- * });
- * // segments is [["key", "value"]]
- * // notes is { "key": "description for key\nplaceholder: example for placeholder - description for placeholder" }
+ * Filter for i18next v4 JSON format.
+ * @see https://www.i18next.com/misc/json-format
  */
-function parseResourceAnnotations(resource, enableArbAnnotations, arbAnnotationHandlers) {
-    if (!enableArbAnnotations) {
-        return [ Object.entries(flatten(resource)), {} ]
-    }
-
-    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
-        }
-    }
-    return [ Object.entries(res), parsedNotes ];
-}
-
 export class I18nextFilter {
+
+    /**
+     * @param {Object} [params] - Configuration options
+     * @param {boolean} [params.enableArbAnnotations=false] - Enable parsing of ARB-style annotations (@key objects)
+     * @param {boolean} [params.enableArrays=false] - Enable array syntax in generated output (vs object notation)
+     * @param {boolean} [params.emitArbAnnotations=false] - Emit ARB annotations in generated output
+     * @param {Object} [params.arbAnnotationHandlers] - Custom handlers for ARB annotation types.
+     *   Each handler is a function(name, data) returning a string or undefined.
+     *   Built-in handlers: description, placeholders, DEFAULT.
+     */
     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 response = {
-            segments: []
+    async parseResource({ resource, sourcePluralForms, targetPluralForms }) {
+        const response = { segments: [] };
+        if (!resource) return response;
+
+        const unParsedResource = JSON.parse(resource);
+        const targetLangs = unParsedResource['@@targetLocales'];
+        Array.isArray(targetLangs) && (response.targetLangs = targetLangs);
+
+        const [parsedResource, notes] = parseResourceAnnotations(
+            unParsedResource,
+            this.enableArbAnnotations,
+            this.arbAnnotationHandlers,
+        );
+
+        // Use provided plural forms or defaults
+        const requiredSourceForms = sourcePluralForms ?? DEFAULT_SOURCE_PLURAL_FORMS;
+        const requiredTargetForms = targetPluralForms ?? ALL_PLURAL_FORMS;
+        const targetFormsSet = new Set(requiredTargetForms);
+
+        // Collect all segments and group potential plurals by baseKey
+        const potentialPluralGroups = new Map(); // baseKey -> Map(suffix -> segment)
+
+        for (const [key, value] of parsedResource) {
+            const seg = {
+                sid: key,
+                str: value,
+                ...(notes[key] && { notes: notes[key] }),
+            };
+            response.segments.push(seg);
+
+            // Check if key is a plural form (e.g., "key_one", "key_other")
+            const underscoreIdx = key.lastIndexOf('_');
+            if (underscoreIdx !== -1) {
+                const suffix = key.slice(underscoreIdx + 1);
+                if (targetFormsSet.has(suffix)) {
+                    const baseKey = key.slice(0, underscoreIdx);
+                    if (!potentialPluralGroups.has(baseKey)) {
+                        potentialPluralGroups.set(baseKey, new Map());
+                    }
+                    potentialPluralGroups.get(baseKey).set(suffix, seg);
+                }
+            }
         }
-        if (resource) {
-            const unParsedResource = JSON.parse(resource);
-            const targetLangs = unParsedResource['@@targetLocales'];
-            Array.isArray(targetLangs) && (response.targetLangs = targetLangs);
-            const [ parsedResource, notes ] = parseResourceAnnotations(
-                unParsedResource,
-                this.enableArbAnnotations,
-                this.arbAnnotationHandlers,
-            );
-            for (const [key, value] of parsedResource) {
-                let seg = { sid: key, str: value };
-                notes[key] && (seg.notes = notes[key]);
-                if (this.enablePluralSuffixes && key.indexOf('_') !== -1 && validPluralSuffixes.has(key.split('_').slice(-1)[0])) {
-                    seg.isSuffixPluralized = true;
+
+        // For groups with all required forms: set pluralForm and generate missing forms
+        for (const [baseKey, forms] of potentialPluralGroups) {
+            const hasAllForms = requiredSourceForms.every(form => forms.has(form));
+            if (!hasAllForms) continue;
+
+            // Set pluralForm on existing segments
+            for (const [suffix, seg] of forms) {
+                seg.pluralForm = suffix;
+            }
+
+            // Generate missing forms from _other
+            const other = forms.get('other');
+            for (const suffix of requiredTargetForms) {
+                if (!forms.has(suffix)) {
+                    response.segments.push({
+                        sid: `${baseKey}_${suffix}`,
+                        str: other.str,
+                        pluralForm: suffix,
+                        ...(other.notes && { notes: other.notes })
+                    });
                 }
-                response.segments.push(seg);
             }
         }
         return response;
     }
 
-    async translateResource({ resource, translator }) {
-        let flatResource = flatten(JSON.parse(resource));
-        for (const entry of Object.entries(flatResource)) {
-            if (!this.enableArbAnnotations || !isArbAnnotations(entry)) {
-                const translation = await translator(...entry);
-                if (translation === null) {
-                    delete flatResource[entry[0]];
-                } else {
-                    flatResource[entry[0]] = translation;
-                    // TODO: deal with pluralized forms as well
-                }
+    /**
+     * Generate a resource file from segments
+     * @param {Object} params
+     * @param {Array} params.segments - Array of segment objects with sid, str, etc.
+     * @param {Function} params.translator - Translator function(seg) that returns translated string
+     * @param {Array} [params.targetPluralForms] - Array of plural forms required for target language
+     * @returns {Promise<string>} JSON string of the generated resource
+     */
+    async generateResource({ segments, translator, targetPluralForms }) {
+        const targetFormsSet = targetPluralForms ? new Set(targetPluralForms) : null;
+        const flatResource = {};
+        for (const seg of segments) {
+            // Skip plural forms not needed for target language
+            if (seg.pluralForm && targetFormsSet && !targetFormsSet.has(seg.pluralForm)) {
+                continue;
             }
-        }
-        if (this.enableArbAnnotations) {
-            for (const entry of Object.entries(flatResource).filter(entry => isArbAnnotations(entry))) {
-                const [key, value] = entry;
-                
-                // Always delete if not emitting annotations
-                if (!this.emitArbAnnotations) {
-                    delete flatResource[key];
-                    continue;
-                }
-                
-                // Only keep if regex matches and corresponding translation exists and is not null
-                const match = extractArbGroupsRegex.exec(key);
-                if (match?.groups) {
-                    const { prefix = '', key: arbKey, attribute } = match.groups;
-                    const sid = `${prefix}${arbKey}`;
-                    if (!Object.prototype.hasOwnProperty.call(flatResource, sid) || flatResource[sid] == null) {
-                        delete flatResource[key];
-                    }
-                } else {
-                    // No regex match, can't determine corresponding translation, so delete
-                    delete flatResource[key];
-                }
+            const translatedStr = await translator(seg);
+            if (translatedStr != null) {
+                flatResource[seg.sid] = translatedStr.str;
             }
         }
+
         return `${JSON.stringify(unflatten(flatResource, { object: !this.enableArrays }), null, 2)}\n`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@l10nmonster/helpers-json",
-    "version": "3.0.0-alpha.16",
+    "version": "3.0.0-alpha.17",
     "description": "Helpers to deal with JSON file formats",
     "type": "module",
     "main": "index.js",

package/utils.js

@@ -1,3 +1,8 @@
+// Intentionally uses `== null` to handle undefined and null
+/* eslint-disable no-eq-null, eqeqeq */
+
+import { flatten } from 'flat';
+
 export const ARB_ANNOTATION_MARKER = "@";
 export const FLATTEN_SEPARATOR = ".";
 
@@ -105,3 +110,63 @@ export function arbPlaceholderHandler(placeholders) {
     }
     return phs.join("\n")
 }
+
+/**
+ * @function parseResourceAnnotations
+ *
+ * @description
+ * Parse resource annotations according to the given configuration.
+ *
+ * @param {object} resource - The resource to parse.
+ * @param {boolean} enableArbAnnotations - Whether to enable annotations
+ * @param {object} arbAnnotationHandlers - An object mapping annotation names to a function which takes an annotation name and its value and returns a string.
+ *
+ * @returns {array} An array with two elements. The first element is an array of key-value pairs for the translatable segments. The second element is an object with the parsed annotations.
+ *
+ * @example
+ * const resource = {
+ *   "key": "value",
+ *   "@key": {
+ *     "description": "description for key",
+ *     "placeholders": {
+ *       "placeholder": {
+ *         "example": "example for placeholder",
+ *         "description": "description for placeholder",
+ *       }
+ *     }
+ *   }
+ * };
+ * const [segments, notes] = parseResourceAnnotations(resource, true, {
+ *   description: (_, data) => (data == null ? undefined : data),
+ *   placeholders: (_, data) => (data == null ? undefined : arbPlaceholderHandler(data)),
+ *   DEFAULT: (name, data) => (data == null ? undefined : `${name}: ${data}`),
+ * });
+ * // segments is [["key", "value"]]
+ * // notes is { "key": "description for key\nplaceholder: example for placeholder - description for placeholder" }
+ */
+export function parseResourceAnnotations(resource, enableArbAnnotations, arbAnnotationHandlers) {
+    if (!enableArbAnnotations) {
+        return [ Object.entries(flatten(resource)), {} ]
+    }
+
+    const { res, notes } = flattenAndSplitResources([], resource)
+    const parsedNotes = {}
+    for (const [key, arbAnnotations] of Object.entries(notes)) {
+        if (typeof arbAnnotations === "object") {
+            const notesList = []
+            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) {
+                        notesList.push(val)
+                    }
+                }
+            }
+            parsedNotes[key] = notesList.join("\n")
+        } else {
+            parsedNotes[key] = arbAnnotations
+        }
+    }
+    return [ Object.entries(res), parsedNotes ];
+}