@l10nmonster/helpers-json 1.0.4 → 3.0.0-alpha.10

package/.releaserc.json

@@ -0,0 +1,31 @@
+{
+  "branches": [
+    "main",
+    {
+      "name": "next",
+      "prerelease": "alpha"
+    },
+    {
+      "name": "beta",
+      "prerelease": "beta"
+    }
+  ],
+  "tagFormat": "@l10nmonster/helpers-json@${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    {
+      "path": "@semantic-release/changelog",
+      "changelogFile": "CHANGELOG.md"
+    },
+    {
+      "path": "@semantic-release/npm",
+      "npmPublish": true
+    },
+    {
+      "path": "@semantic-release/git",
+      "assets": ["CHANGELOG.md", "package.json"],
+      "message": "chore(release): @l10nmonster/helpers-json@${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

package/README.md

@@ -1,14 +1,375 @@
-# L10n Monster JSON Helpers
+# @l10nmonster/helpers-json
+
+L10n Monster helper for JSON file formats, supporting both generic JSON structures and specialized formats like i18next and ARB (Application Resource Bundle).
+
+## Installation
+
+```bash
+npm install @l10nmonster/helpers-json
+```
+
+## Features
 
 ### 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 arrays, nested keys and plurals as defined by the [i18next JSON v4](https://www.i18next.com/misc/json-format) format.
+A comprehensive filter for JSON files that supports:
+- **ARB annotations** as defined by the [ARB specification](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification)
+- **i18next v4 format** including arrays, nested keys, and plurals
+- **Generic JSON** structures with flexible key handling
+- **Placeholder processing** with multiple syntaxes
+
+### Supported Formats
+
+#### i18next JSON v4
+The industry standard JSON format for internationalization:
+
+```json
+{
+  "welcome": "Welcome {{name}}!",
+  "items_one": "{{count}} item",
+  "items_other": "{{count}} items",
+  "nested": {
+    "key": "Nested value"
+  },
+  "arrayValue": ["First", "Second", "Third"]
+}
+```
+
+#### ARB (Application Resource Bundle)
+Google's JSON-based localization format:
+
+```json
+{
+  "welcome": "Welcome {name}!",
+  "@welcome": {
+    "description": "Welcome message",
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+### Basic Configuration
+
+```javascript
+import { Filter } from '@l10nmonster/helpers-json';
+
+const jsonFilter = new Filter({
+    enableArbAnnotations: true,    // Support ARB @-prefixed annotations
+    enablePluralSuffixes: true,    // Support i18next plural suffixes (_one, _other)
+    emitArbAnnotations: true,      // Include ARB annotations in output
+    enableArrays: true            // Support array values
+});
+```
+
+### Integration with L10n Monster
+
+```javascript
+// l10nmonster.config.mjs
+import { FsSource, FsTarget } from '@l10nmonster/core';
+import { Filter, i18next } from '@l10nmonster/helpers-json';
+
+export default {
+    channels: [{
+        source: new FsSource({ 
+            globs: ['locales/en/**/*.json'] 
+        }),
+        target: new FsTarget({ 
+            targetPath: (lang, resourceId) => 
+                resourceId.replace('/en/', `/${lang}/`)
+        })
+    }],
+    
+    contentTypes: [{
+        name: 'i18next-json',
+        resourceFilter: new Filter({
+            enablePluralSuffixes: true,
+            enableArrays: true
+        }),
+        decoders: [i18next.phDecoder],
+        textEncoders: ['bracketEncoder']
+    }]
+};
+```
+
+## Configuration Options
+
+### Filter Options
+
+- **`enableArbAnnotations`** (boolean): Enable ARB annotation support
+- **`enablePluralSuffixes`** (boolean): Enable i18next plural suffix handling
+- **`emitArbAnnotations`** (boolean): Include ARB annotations in translated output
+- **`enableArrays`** (boolean): Support JSON array values
+- **`maxDepth`** (number): Maximum nesting depth for nested objects
+- **`keyDelimiter`** (string): Delimiter for nested key flattening
+
+### Placeholder Decoders
+
+The package includes specialized placeholder decoders:
+
+```javascript
+import { i18next } from '@l10nmonster/helpers-json';
+
+// i18next placeholder decoder for {{param}} and $t(key) syntax
+const decoder = i18next.phDecoder();
+```
+
+## Supported JSON Structures
+
+### Flat Structure
+```json
+{
+  "key1": "Simple value",
+  "key2": "Value with {{placeholder}}"
+}
+```
+
+### Nested Structure
+```json
+{
+  "section": {
+    "subsection": {
+      "key": "Deeply nested value"
+    }
+  }
+}
+```
+
+### Plurals (i18next)
+```json
+{
+  "item_one": "{{count}} item",
+  "item_other": "{{count}} items",
+  "item_zero": "No items"
+}
+```
+
+### Arrays
+```json
+{
+  "fruits": ["Apple", "Banana", "Orange"],
+  "mixed": [
+    "String value",
+    {"nested": "object"}
+  ]
+}
+```
+
+### ARB with Annotations
+```json
+{
+  "pageTitle": "My App",
+  "@pageTitle": {
+    "description": "Title of the application"
+  },
+  "greeting": "Hello {name}",
+  "@greeting": {
+    "description": "Greeting message",
+    "placeholders": {
+      "name": {
+        "type": "String",
+        "example": "John"
+      }
+    }
+  }
+}
+```
+
+## Placeholder Formats
 
-```js
-this.resourceFilter = new filters.JsonFilter({
-        enableArbAnnotations: true,
-        enablePluralSuffixes: true,
-        emitArbAnnotations: true,
-        enableArrays: true
+### i18next Format
+- **Interpolation**: `{{variable}}`
+- **Translation function**: `$t(namespace:key)`
+- **Formatting**: `{{variable, format}}`
+
+### ARB Format
+- **Simple placeholders**: `{variable}`
+- **Typed placeholders**: `{count, number}`, `{date, date}`
+
+### Generic Formats
+- **Brace placeholders**: `{param}`
+- **Percent placeholders**: `%s`, `%d`, `%1$s`
+
+## Advanced Features
+
+### Namespace Support
+
+```javascript
+// Namespace-aware configuration
+const filter = new Filter({
+    enableNamespaces: true,
+    namespaceDelimiter: ':'
 });
 ```
+
+### Custom Key Processing
+
+```javascript
+const filter = new Filter({
+    keyProcessor: (key, value, context) => {
+        // Custom logic for key transformation
+        if (key.startsWith('_')) {
+            return null; // Skip private keys
+        }
+        return { key, value };
+    }
+});
+```
+
+### Validation and Schema
+
+```javascript
+const filter = new Filter({
+    validateStructure: true,
+    requiredKeys: ['title', 'description'],
+    schema: {
+        type: 'object',
+        properties: {
+            title: { type: 'string' },
+            description: { type: 'string' }
+        }
+    }
+});
+```
+
+## Integration Examples
+
+### React i18next Project
+
+```javascript
+// l10nmonster.config.mjs
+import { Filter, i18next } from '@l10nmonster/helpers-json';
+
+export default {
+    channels: [{
+        source: new FsSource({ 
+            globs: ['public/locales/en/**/*.json'] 
+        }),
+        target: new FsTarget({ 
+            targetPath: (lang, resourceId) => 
+                resourceId.replace('/en/', `/${lang}/`)
+        })
+    }],
+    
+    contentTypes: [{
+        name: 'react-i18next',
+        resourceFilter: new Filter({
+            enablePluralSuffixes: true,
+            enableArrays: true,
+            enableNamespaces: true
+        }),
+        decoders: [i18next.phDecoder]
+    }]
+};
+```
+
+### Flutter ARB Project
+
+```javascript
+export default {
+    channels: [{
+        source: new FsSource({ 
+            globs: ['lib/l10n/app_en.arb'] 
+        }),
+        target: new FsTarget({ 
+            targetPath: (lang, resourceId) => 
+                resourceId.replace('_en.arb', `_${lang}.arb`)
+        })
+    }],
+    
+    contentTypes: [{
+        name: 'flutter-arb',
+        resourceFilter: new Filter({
+            enableArbAnnotations: true,
+            emitArbAnnotations: true
+        })
+    }]
+};
+```
+
+### Generic JSON API
+
+```javascript
+export default {
+    channels: [{
+        source: new FsSource({ 
+            globs: ['api/messages/en.json'] 
+        }),
+        target: new FsTarget({ 
+            targetPath: (lang, resourceId) => 
+                resourceId.replace('/en.json', `/${lang}.json`)
+        })
+    }],
+    
+    contentTypes: [{
+        name: 'api-json',
+        resourceFilter: new Filter({
+            enableArrays: true,
+            maxDepth: 3
+        })
+    }]
+};
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+The test suite covers:
+- JSON parsing and generation
+- ARB annotation handling
+- i18next plural suffix processing
+- Placeholder extraction and preservation
+- Nested structure handling
+- Array value processing
+
+## Performance Considerations
+
+### Large Files
+- Use `maxDepth` to limit processing depth
+- Consider splitting large JSON files
+- Enable streaming for very large datasets
+
+### Memory Usage
+- Arrays are loaded entirely into memory
+- Nested objects are processed recursively
+- Consider file size limits for production use
+
+## Migration from v2
+
+### Configuration Changes
+```javascript
+// v2 (deprecated)
+this.resourceFilter = new filters.JsonFilter();
+
+// v3 (current)
+import { Filter } from '@l10nmonster/helpers-json';
+const filter = new Filter();
+```
+
+### Import Updates
+```javascript
+// v2
+const { helpers } = require('@l10nmonster/helpers');
+
+// v3
+import { Filter, i18next } from '@l10nmonster/helpers-json';
+```
+
+## Requirements
+
+- Node.js >= 22.11.0
+- @l10nmonster/core (peer dependency)
+
+## Related Documentation
+
+- [i18next Documentation](https://www.i18next.com/)
+- [ARB Specification](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification)
+- [L10n Monster Core Documentation](../core/README.md)

package/i18next.js

@@ -2,22 +2,55 @@
 /* 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');
+import { flatten, unflatten } from 'flat';
+import { regex } from '@l10nmonster/core';
+import { flattenAndSplitResources, ARB_ANNOTATION_MARKER, arbPlaceholderHandler } from './utils.js';
 
-const isArbAnnotations = e => e[0].split('.').slice(-2)[0].startsWith(ARB_ANNOTATION_MARKER);
+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>\S+)\.(?<attribute>\S+)/;
+const extractArbGroupsRegex = /(?<prefix>.+?\.)?@(?<key>[^.]+)\.(?<attribute>.+)/;
 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
+ *
+ * @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" }
+ */
 function parseResourceAnnotations(resource, enableArbAnnotations, arbAnnotationHandlers) {
     if (!enableArbAnnotations) {
-        return [ Object.entries(flat.flatten(resource)), {} ]
+        return [ Object.entries(flatten(resource)), {} ]
     }
 
     const { res, notes } = flattenAndSplitResources([], resource)
@@ -42,7 +75,7 @@ function parseResourceAnnotations(resource, enableArbAnnotations, arbAnnotationH
     return [ Object.entries(res), parsedNotes ];
 }
 
-exports.Filter = class I18nextFilter {
+export class I18nextFilter {
     constructor(params) {
         this.enableArbAnnotations = params?.enableArbAnnotations || false;
         this.enablePluralSuffixes = params?.enablePluralSuffixes || false;
@@ -80,11 +113,11 @@ exports.Filter = class I18nextFilter {
     }
 
     async translateResource({ resource, translator }) {
-        let flatResource = flat.flatten(JSON.parse(resource));
+        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 === undefined) {
+                if (translation === null) {
                     delete flatResource[entry[0]];
                 } else {
                     flatResource[entry[0]] = translation;
@@ -94,14 +127,29 @@ exports.Filter = class I18nextFilter {
         }
         if (this.enableArbAnnotations) {
             for (const entry of Object.entries(flatResource).filter(entry => isArbAnnotations(entry))) {
-                const arbGroups = extractArbGroupsRegex.exec(entry[0]).groups;
-                const sid = `${arbGroups.prefix ?? ''}${arbGroups.key}`;
-                if (!this.emitArbAnnotations || !flatResource[sid]) {
-                    delete flatResource[entry[0]];
+                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];
                 }
             }
         }
-        return JSON.stringify(flat.unflatten(flatResource, { object: !this.enableArrays }), null, 2) + '\n';
+        return `${JSON.stringify(unflatten(flatResource, { object: !this.enableArrays }), null, 2)}\n`;
     }
 }
 
@@ -109,7 +157,7 @@ exports.Filter = class I18nextFilter {
 // - "keyNesting": "reuse $t(keyDeep.inner)", or
 // - "keyInterpolate": "replace this {{value}}"
 // See: https://www.i18next.com/misc/json-format#i18next-json-v4
-exports.phDecoder = regex.decoderMaker(
+export const phDecoder = regex.decoderMaker(
     'i18nextKey',
     /(?<nestingPh>\$t\([\w:.]+\))|(?<doubleBracePh>{{[^}]+}})/g,
     (groups) => ({ t: 'x', v: groups.nestingPh ?? groups.doubleBracePh })

package/index.js

@@ -1 +1 @@
-exports.i18next = { ...require('./i18next') };
+export * as i18next from './i18next.js';

package/package.json

@@ -1,17 +1,21 @@
 {
-  "name": "@l10nmonster/helpers-json",
-  "version": "1.0.4",
-  "description": "Helpers to deal with JSON file formats",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "Diego Lagunas",
-  "license": "MIT",
-  "dependencies": {
-    "flat": "^5.0.2"
-  },
-  "peerDependencies": {
-    "@l10nmonster/helpers": "^1"
-  }
+    "name": "@l10nmonster/helpers-json",
+    "version": "3.0.0-alpha.10",
+    "description": "Helpers to deal with JSON file formats",
+    "type": "module",
+    "main": "index.js",
+    "scripts": {
+        "test": "node --test"
+    },
+    "author": "Diego Lagunas",
+    "license": "MIT",
+    "dependencies": {
+        "flat": "^6"
+    },
+    "peerDependencies": {
+        "@l10nmonster/core": "^3.0.0-alpha.0"
+    },
+    "engines": {
+        "node": ">=22.11.0"
+    }
 }

package/utils.js

@@ -1,13 +1,13 @@
-const ARB_ANNOTATION_MARKER = "@";
-const FLATTEN_SEPARATOR = ".";
+export const ARB_ANNOTATION_MARKER = "@";
+export 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}}
+ * @param {object} obj Object to parse
+ * @returns {{res: object, notes: object}}
  *
  * ```
  * const obj = {
@@ -58,7 +58,7 @@ const FLATTEN_SEPARATOR = ".";
  * )
  * ```
  */
-function flattenAndSplitResources(keys, obj) {
+export 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.
@@ -95,20 +95,13 @@ function flattenAndSplitResources(keys, obj) {
  * assert(ph === "PH({{count}}|1|number of tickets)")
  * ```
  *
- * @param {{ [key: string]: value }} ARB placeholders
+ * @param {{ [key: string]: object }} placeholders ARB placeholders
  * @returns {string} placeholders formatted in PH() and separated by "\n"
  */
-function arbPlaceholderHandler(placeholders) {
+export 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,
-}