@l10nmonster/helpers-json 1.0.3 → 3.0.0-alpha.1

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 >= 20.12.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,9 +2,9 @@
 /* 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 validPluralSuffixes = new Set(['one', 'other', 'zero', 'two', 'few', 'many']);
@@ -15,9 +15,42 @@ const defaultArbAnnotationHandlers = {
     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;
@@ -55,30 +88,32 @@ exports.Filter = class I18nextFilter {
     }
 
     async parseResource({ resource }) {
-        const segments = [];
-        if (!resource) {
-            return { segments };
+        const response = {
+            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]);
-            if (this.enablePluralSuffixes && key.indexOf('_') !== -1 && validPluralSuffixes.has(key.split('_').slice(-1)[0])) {
-                seg.isSuffixPluralized = true;
+        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;
+                }
+                response.segments.push(seg);
             }
-            segments.push(seg);
         }
-        return {
-            segments,
-        };
+        return response;
     }
 
     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);
@@ -99,7 +134,7 @@ exports.Filter = class I18nextFilter {
                 }
             }
         }
-        return JSON.stringify(flat.unflatten(flatResource, { object: !this.enableArrays }), null, 2) + '\n';
+        return `${JSON.stringify(unflatten(flatResource, { object: !this.enableArrays }), null, 2)}\n`;
     }
 }
 
@@ -107,7 +142,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,18 @@
 {
-  "name": "@l10nmonster/helpers-json",
-  "version": "1.0.3",
-  "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.1",
+    "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": "file:../core"
+    }
 }

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,
-}