@l10nmonster/helpers-android 3.0.0-alpha.9 → 3.0.2

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## @l10nmonster/helpers-android [3.0.2](https://public-github/l10nmonster/l10nmonster/compare/@l10nmonster/helpers-android@3.0.1...@l10nmonster/helpers-android@3.0.2) (2025-12-23)
+
+
+### Bug Fixes
+
+* Improve type definitions and checks ([826b412](https://public-github/l10nmonster/l10nmonster/commit/826b412f0f7e761d404165a243b0c2b26c416ac1))
+
+
+
+
+
+### Dependencies
+
+* **@l10nmonster/core:** upgraded to 3.1.1
+
+## @l10nmonster/helpers-android [3.0.1](https://public-github/l10nmonster/l10nmonster/compare/@l10nmonster/helpers-android@3.0.0...@l10nmonster/helpers-android@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/filter.js

@@ -7,6 +7,8 @@ import { XMLParser, XMLBuilder } from 'fast-xml-parser';
 import { default as formatXml } from 'xml-formatter';
 import { logVerbose } from '@l10nmonster/core';
 
+/** @typedef {import('@l10nmonster/core').ResourceFilter} ResourceFilter */
+
 function collapseTextNodes(node) {
     return node.map(e => e['#text']).join('').trim();
 }
@@ -19,6 +21,7 @@ function isTranslatableNode(resNode, str) {
 
 /**
  * Class representing an AndroidFilter for parsing and translating Android resource files.
+ * @implements {ResourceFilter}
  */
 export class AndroidXMLFilter {
 
@@ -35,9 +38,10 @@ export class AndroidXMLFilter {
      * Parse an Android resource file and extract translatable segments.
      * @param {Object} params - Parameters for parsing the resource.
      * @param {string} params.resource - The XML content of the Android resource file.
+     * @param {string[]} [params.targetPluralForms] - Array of plural forms required for target languages.
      * @returns {Promise<Object>} An object containing the extracted segments.
      */
-    async parseResource({ resource }) {
+    async parseResource({ resource, targetPluralForms }) {
         const segments = [];
         const parsingOptions = {
             ignoreAttributes: false,
@@ -52,6 +56,7 @@ export class AndroidXMLFilter {
             parseTagValue: false,
             trimValues: true,
         };
+
         const parser = new XMLParser(parsingOptions);
         for (const rootNode of parser.parse(resource)) {
             if ('resources' in rootNode) {
@@ -71,17 +76,42 @@ export class AndroidXMLFilter {
                             lastComment = null;
                         }
                     } else if ('plurals' in resNode) { // TODO: support string-array
+                        const pluralName = resNode[':@'].name;
+                        const pluralForms = new Map(); // quantity -> { seg, notes }
+                        let pluralComment = lastComment;
+
+                        // Collect existing plural forms
                         for (const itemNode of resNode.plurals) {
                             if ('#comment' in itemNode) {
-                                lastComment = itemNode['#comment'].map(e => e['#text']).join('').trim();
+                                pluralComment = itemNode['#comment'].map(e => e['#text']).join('').trim();
                             } else if ('item' in itemNode) {
+                                const quantity = itemNode[':@'].quantity;
                                 const seg = {
-                                    sid: `${resNode[':@'].name}_${itemNode[':@'].quantity}`,
-                                    isSuffixPluralized: true,
+                                    sid: `${pluralName}_${quantity}`,
+                                    pluralForm: quantity,
                                     str: collapseTextNodes(itemNode.item)
                                 };
-                                lastComment && (seg.notes = lastComment);
-                                segments.push(seg);
+                                pluralComment && (seg.notes = pluralComment);
+                                pluralForms.set(quantity, seg);
+                            }
+                        }
+
+                        // Android <plurals> element explicitly defines plural rules
+                        // Expansion can happen as long as 'other' form is present
+                        const otherForm = pluralForms.get('other');
+
+                        // Add forms in natural plural order (existing or generated from 'other')
+                        for (const form of targetPluralForms) {
+                            if (pluralForms.has(form)) {
+                                segments.push(pluralForms.get(form));
+                            } else if (otherForm) {
+                                // Generate missing form from 'other'
+                                segments.push({
+                                    sid: `${pluralName}_${form}`,
+                                    pluralForm: form,
+                                    str: otherForm.str,
+                                    ...(otherForm.notes && { notes: otherForm.notes })
+                                });
                             }
                         }
                         lastComment = null;
@@ -102,9 +132,10 @@ export class AndroidXMLFilter {
      * @param {Object} params - Parameters for translating the resource.
      * @param {string} params.resource - The XML content of the Android resource file.
      * @param {Function} params.translator - A function that translates a string given its ID and source text.
+     * @param {string[]} [params.targetPluralForms] - Array of plural forms required for the target language.
      * @returns {Promise<string|null>} The translated XML content, or null if no translations were made.
      */
-    async translateResource({ resource, translator }) {
+    async translateResource({ resource, translator, targetPluralForms }) {
         const parsingOptions = {
             ignoreAttributes: false,
             processEntities: true,
@@ -118,6 +149,7 @@ export class AndroidXMLFilter {
             parseTagValue: false,
             trimValues: true,
         };
+
         const parser = new XMLParser(parsingOptions);
         const parsedResource = parser.parse(resource);
         const nodesToDelete = [];
@@ -138,26 +170,51 @@ export class AndroidXMLFilter {
                         } else {
                             nodesToDelete.push(resNode);
                         }
-                    } else if ('plurals' in resNode) { // TODO: deal with plurals of the target language, not the source
-                        let dropPlural = false;
-                        const itemNodesToDelete = []
+                    } else if ('plurals' in resNode) {
+                        const pluralName = resNode[':@'].name;
+
+                        // Collect source plural forms
+                        const sourceForms = new Map(); // quantity -> { text, itemNode }
                         for (const itemNode of resNode.plurals) {
-                            if ('#comment' in itemNode) {
-                                itemNodesToDelete.push(itemNode)
-                                // eslint-disable-next-line no-continue
-                                continue;
+                            if ('item' in itemNode) {
+                                sourceForms.set(itemNode[':@'].quantity, {
+                                    text: collapseTextNodes(itemNode.item),
+                                    itemNode
+                                });
+                            }
+                        }
+
+                        // Get 'other' form for generating missing target forms
+                        // Android <plurals> is explicitly a plural, so we can expand as long as 'other' exists
+                        const otherForm = sourceForms.get('other');
+
+                        // Build new plurals node with only required target forms in CLDR order
+                        const newPluralItems = [];
+                        let dropPlural = false;
+
+                        for (const form of targetPluralForms) {
+                            const sourceForm = sourceForms.get(form) ?? otherForm;
+                            if (!sourceForm) {
+                                // Can't generate this required form - no source and no fallback
+                                dropPlural = true;
+                                break;
                             }
-                            const translation = await translator(`${resNode[':@'].name}_${itemNode[':@'].quantity}`, collapseTextNodes(itemNode.item));
+                            const translation = await translator(`${pluralName}_${form}`, sourceForm.text);
                             if (translation === undefined) {
                                 dropPlural = true;
-                            } else {
-                                itemNode.item = [ { '#text': translation } ];
+                                break;
                             }
+                            newPluralItems.push({
+                                item: [{ '#text': translation }],
+                                ':@': { quantity: form }
+                            });
                         }
-                        resNode.plurals = resNode.plurals.filter(n => !itemNodesToDelete.includes(n))
-                        if (dropPlural) {
+
+                        if (dropPlural || newPluralItems.length === 0) {
                             nodesToDelete.push(resNode);
                         } else {
+                            // Replace plurals with new items containing only target forms
+                            resNode.plurals = newPluralItems;
                             translated++;
                         }
                     } else {
@@ -172,7 +229,8 @@ export class AndroidXMLFilter {
         }
         const builder = new XMLBuilder(parsingOptions);
         const roughXML = builder.build(parsedResource);
-        // eslint-disable-next-line prefer-template
-        return formatXml(roughXML, { collapseContent: true, indentation: this.indentation, lineSeparator: '\n' }) + '\n';
+         
+        // @ts-ignore - xml-formatter types don't match actual module export
+        return `${formatXml(roughXML, { collapseContent: true, indentation: this.indentation, lineSeparator: '\n' })}\n`;
     }
 }

package/index.js

@@ -5,6 +5,8 @@ const androidControlCharsToDecode = {
     n: '\n',
     t: '\t',
 };
+
+/** @type {import('@l10nmonster/core').DecoderFunction} */
 export const escapesDecoder = regex.decoderMaker(
     'androidEscapesDecoder',
     /(?<node>\\(?<escapedChar>[@?\\'"])|\\(?<escapedControl>[nt])|\\u(?<codePoint>[0-9A-Za-z]{4}))/g,
@@ -16,7 +18,10 @@ export const escapesDecoder = regex.decoderMaker(
     )
 );
 
-// Android lint doesn't accept % but accepts %%.  % should be replaced with '\u0025' but %% shouldn't
+/**
+ * Android lint doesn't accept % but accepts %%.  % should be replaced with '\u0025' but %% shouldn't
+ * @type {import('@l10nmonster/core').TextEncoderFunction}
+ */
 export const escapesEncoder = (str, flags = {}) => {
     let escapedStr = str.replaceAll(/[@\\'"]/g, '\\$&').replaceAll('\t', '\\t').replaceAll('\n', '\\n').replaceAll(/(?<!%)%(?!%)/g, '\\u0025');
     // eslint-disable-next-line prefer-template
@@ -26,9 +31,14 @@ export const escapesEncoder = (str, flags = {}) => {
     return escapedStr;
 };
 
+/** @type {import('@l10nmonster/core').PartTransformer} */
+// @ts-ignore - Part union type narrowing not supported by TypeScript in this pattern
 export const spaceCollapser = (parts) => parts.map(p => (p.t === 's' ? { ...p, v: p.v.replaceAll(/[ \f\n\r\t\v\u2028\u2029]+/g, ' ')} : p));
 
-// C-style placeholders (based on the ios one)
+/**
+ * C-style placeholders (based on the ios one)
+ * @type {import('@l10nmonster/core').DecoderFunction}
+ */
 export const phDecoder = regex.decoderMaker(
     'iosPHDecoder',
     /(?<tag>%(?:\d\$)?[0#+-]?[0-9*]*\.?\d*[hl]{0,2}[jztL]?[diuoxXeEfgGaAcpsSn])/g,

package/package.json

@@ -1,11 +1,12 @@
 {
     "name": "@l10nmonster/helpers-android",
-    "version": "3.0.0-alpha.9",
+    "version": "3.0.2",
     "description": "Helpers to deal with Android file formats",
     "type": "module",
     "main": "index.js",
     "scripts": {
-        "test": "node --test"
+        "test": "node --test",
+        "typecheck": "tsc --noEmit"
     },
     "author": "Diego Lagunas",
     "license": "MIT",
@@ -14,6 +15,6 @@
         "xml-formatter": "^3"
     },
     "peerDependencies": {
-        "@l10nmonster/core": "^3.0.0-alpha.0"
+        "@l10nmonster/core": "3.1.1"
     }
 }

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": [
+    "*.js",
+    "**/*.js"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/node_modules",
+    "test/**",
+    "tests/**",
+    "**/*.test.js",
+    "**/*.spec.js",
+    "dist/**",
+    "ui/**",
+    "types/**"
+  ]
+}

package/.releaserc.json

@@ -1,31 +0,0 @@
-{
-  "branches": [
-    "main",
-    {
-      "name": "next",
-      "prerelease": "alpha"
-    },
-    {
-      "name": "beta",
-      "prerelease": "beta"
-    }
-  ],
-  "tagFormat": "@l10nmonster/helpers-android@${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-android@${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
-    }
-  ]
-}