@l10nmonster/helpers-json 3.0.0-alpha.9 → 3.0.1

package/.releaserc.json

@@ -20,7 +20,7 @@
     },
     {
       "path": "@semantic-release/npm",
-      "npmPublish": true
+      "npmPublish": false
     },
     {
       "path": "@semantic-release/git",

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## @l10nmonster/helpers-json [3.0.1](https://public-github/l10nmonster/l10nmonster/compare/@l10nmonster/helpers-json@3.0.0...@l10nmonster/helpers-json@3.0.1) (2025-12-20)
+
+
+### Bug Fixes
+
+* Add proper pluralization expansion support ([3d062bb](https://public-github/l10nmonster/l10nmonster/commit/3d062bbb3272c61e969b419a56a7a5e347ab96c6))
+* Pluralization improvements ([5964250](https://public-github/l10nmonster/l10nmonster/commit/596425092c425cc8d6c312ef58509c4c3c537431))
+* **server:** Fix cart cleanup ([9bbcab9](https://public-github/l10nmonster/l10nmonster/commit/9bbcab93e1fd20aeb09f59c828665159f091f37c))
+
 # Changelog
 
 All notable changes to this project will be documented in this file.

package/i18next.js

@@ -2,13 +2,13 @@
 /* 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 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 +16,207 @@ 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,
+        );
+
+        const targetFormsSet = new Set(targetPluralForms);
+
+        // 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
+        // We need to reorder segments so all forms of a plural group are together in CLDR order
+        const pluralGroupsToReorder = new Map(); // baseKey -> { firstIndex, forms: Map(suffix -> seg) }
+
+        for (const [baseKey, forms] of potentialPluralGroups) {
+            const hasAllForms = sourcePluralForms.every(form => forms.has(form));
+            if (!hasAllForms) continue;
+
+            // Find the first index of this plural group in segments
+            let firstIndex = -1;
+            for (let i = 0; i < response.segments.length; i++) {
+                if (forms.has(response.segments[i].sid?.split('_').pop()) &&
+                    response.segments[i].sid?.startsWith(baseKey + '_')) {
+                    firstIndex = i;
+                    break;
                 }
-                response.segments.push(seg);
             }
+
+            // 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 targetPluralForms) {
+                if (!forms.has(suffix)) {
+                    forms.set(suffix, {
+                        sid: `${baseKey}_${suffix}`,
+                        str: other.str,
+                        pluralForm: suffix,
+                        ...(other.notes && { notes: other.notes })
+                    });
+                }
+            }
+
+            pluralGroupsToReorder.set(baseKey, { firstIndex, forms });
+        }
+
+        // Rebuild segments with plural groups in correct order
+        if (pluralGroupsToReorder.size > 0) {
+            const newSegments = [];
+            const processedPluralKeys = new Set();
+
+            for (const seg of response.segments) {
+                const underscoreIdx = seg.sid.lastIndexOf('_');
+                const suffix = underscoreIdx !== -1 ? seg.sid.slice(underscoreIdx + 1) : null;
+                const baseKey = underscoreIdx !== -1 ? seg.sid.slice(0, underscoreIdx) : null;
+
+                if (baseKey && pluralGroupsToReorder.has(baseKey) && !processedPluralKeys.has(baseKey)) {
+                    // Insert all forms of this plural group in CLDR order
+                    processedPluralKeys.add(baseKey);
+                    const { forms } = pluralGroupsToReorder.get(baseKey);
+                    for (const form of targetPluralForms) {
+                        if (forms.has(form)) {
+                            newSegments.push(forms.get(form));
+                        }
+                    }
+                } else if (!baseKey || !pluralGroupsToReorder.has(baseKey)) {
+                    // Non-plural segment
+                    newSegments.push(seg);
+                }
+                // Skip plural segments that were already added via the group
+            }
+
+            response.segments = newSegments;
         }
+
         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;
+
+        // Collect translations
+        const translations = new Map(); // sid -> translatedStr
+        const pluralGroups = new Map(); // baseKey -> Set of sids
+
+        for (const seg of segments) {
+            // Skip plural forms not needed for target language
+            if (seg.pluralForm && targetFormsSet && !targetFormsSet.has(seg.pluralForm)) {
+                continue;
+            }
+            const translatedStr = await translator(seg);
+            if (translatedStr != null) {
+                translations.set(seg.sid, translatedStr.str);
+
+                // Track plural groups
+                if (seg.pluralForm) {
+                    const underscoreIdx = seg.sid.lastIndexOf('_');
+                    if (underscoreIdx !== -1) {
+                        const baseKey = seg.sid.slice(0, underscoreIdx);
+                        if (!pluralGroups.has(baseKey)) {
+                            pluralGroups.set(baseKey, new Set());
+                        }
+                        pluralGroups.get(baseKey).add(seg.sid);
+                    }
                 }
             }
         }
-        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];
+
+        // Build flatResource with plural forms grouped and ordered
+        const flatResource = {};
+        const processedPluralKeys = new Set();
+
+        for (const seg of segments) {
+            if (!translations.has(seg.sid)) continue;
+
+            if (seg.pluralForm) {
+                const underscoreIdx = seg.sid.lastIndexOf('_');
+                const baseKey = underscoreIdx !== -1 ? seg.sid.slice(0, underscoreIdx) : null;
+
+                if (baseKey && pluralGroups.has(baseKey) && !processedPluralKeys.has(baseKey)) {
+                    // Output all forms of this plural group in CLDR order
+                    processedPluralKeys.add(baseKey);
+                    for (const form of targetPluralForms) {
+                        const sid = `${baseKey}_${form}`;
+                        if (translations.has(sid)) {
+                            flatResource[sid] = translations.get(sid);
+                        }
                     }
-                } else {
-                    // No regex match, can't determine corresponding translation, so delete
-                    delete flatResource[key];
                 }
+                // Skip individual plural forms - they were added via the group
+            } else {
+                flatResource[seg.sid] = translations.get(seg.sid);
             }
         }
+
         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.9",
+    "version": "3.0.1",
     "description": "Helpers to deal with JSON file formats",
     "type": "module",
     "main": "index.js",
@@ -13,7 +13,7 @@
         "flat": "^6"
     },
     "peerDependencies": {
-        "@l10nmonster/core": "^3.0.0-alpha.0"
+        "@l10nmonster/core": "3.1.0"
     },
     "engines": {
         "node": ">=22.11.0"

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 ];
+}