@l10nmonster/helpers-android 1.0.0 → 3.0.0-alpha.1

package/README.md

@@ -1,18 +1,242 @@
-# L10n Monster Android Helpers
+# @l10nmonster/helpers-android
 
-|Module|Export|Description|
+L10n Monster helper for Android XML resource files, providing filters, decoders, and encoders for Android app localization.
+
+## Installation
+
+```bash
+npm install @l10nmonster/helpers-android
+```
+
+## Components
+
+|Component|Export|Description|
 |---|---|---|
-|`helpers-android`|`Filter`|Filter for Android xml files.|
-|`helpers-android`|`escapesDecoder`|Decoder for escaped chars like `\n` and `\u00a0`.|
-|`helpers-android`|`spaceCollapser`|Decoder to convert multiple whitespace into a single space.|
-|`helpers-android`|`phDecoder`|Decoder for `%d` style placeholders.|
-|`helpers-android`|`escapesEncoder`|Encoder for escaped chars as required by Android.|
+|**Filter**|`Filter`|Resource filter for Android XML files|
+|**Decoders**|||
+||`escapesDecoder`|Decoder for escaped chars like `\n` and `\u00a0`|
+||`spaceCollapser`|Decoder to convert multiple whitespace into single space|
+||`phDecoder`|Decoder for `%d` style placeholders|
+|**Encoders**|||
+||`escapesEncoder`|Encoder for escaped chars as required by Android|
+
+## Usage
 
+### Android XML Filter
 
-```js
-this.resourceFilter = new android.Filter({
-    comment: 'pre',
+```javascript
+import { Filter } from '@l10nmonster/helpers-android';
+
+const androidFilter = new Filter({
+    comment: 'pre'  // Options: 'pre', 'post', 'right'
 });
 ```
 
-A filter for XML files used in Android apps. The `comment` property specifies whether developer notes are placed before, after, or on the same line (`pre`, `post`, `right` respectively).
+The filter processes Android XML resource files (`strings.xml`, `plurals.xml`, etc.) and handles:
+- String resources with proper escaping
+- Plural forms (quantity="one", "other", etc.)
+- Comments and developer notes positioning
+- CDATA sections for complex text
+- Resource attributes (`translatable`, `formatted`, etc.)
+
+### Comment Positioning
+
+- **`pre`**: Places developer comments before the string element
+- **`post`**: Places comments after the string element  
+- **`right`**: Places comments on the same line as the string
+
+### Decoders and Encoders
+
+```javascript
+import { 
+    escapesDecoder, 
+    spaceCollapser, 
+    phDecoder,
+    escapesEncoder 
+} from '@l10nmonster/helpers-android';
+
+// Use in content type configuration
+const contentType = {
+    name: 'android-strings',
+    resourceFilter: androidFilter,
+    decoders: [escapesDecoder, spaceCollapser, phDecoder],
+    textEncoders: [escapesEncoder]
+};
+```
+
+## Supported Android Features
+
+### String Resources
+- Basic string elements: `<string name="key">value</string>`
+- Formatted strings with placeholders: `%s`, `%d`, `%1$s`
+- Non-translatable strings: `translatable="false"`
+- Formatted attribute: `formatted="false"`
+
+### Plurals
+- Quantity-based plurals: `zero`, `one`, `two`, `few`, `many`, `other`
+- Proper plural form handling per Android guidelines
+
+### Text Formatting
+- Escape sequences: `\n`, `\t`, `\u0020`, etc.
+- HTML tags in strings (preserved as placeholders)
+- CDATA sections for complex markup
+- Apostrophe and quote escaping
+
+### XML Features
+- XML entities (`&lt;`, `&gt;`, `&amp;`, etc.)
+- Comments and developer notes
+- Resource arrays (basic support)
+
+## Configuration Examples
+
+### Basic Android Project
+
+```javascript
+// l10nmonster.config.mjs
+import { FsSource, FsTarget } from '@l10nmonster/core';
+import { Filter } from '@l10nmonster/helpers-android';
+
+export default {
+    channels: [{
+        source: new FsSource({ 
+            globs: ['app/src/main/res/values/strings.xml'] 
+        }),
+        target: new FsTarget({ 
+            targetPath: (lang, resourceId) => 
+                resourceId.replace('/values/', `/values-${lang}/`)
+        })
+    }],
+    
+    contentTypes: [{
+        name: 'android-xml',
+        resourceFilter: new Filter({ comment: 'pre' })
+    }]
+};
+```
+
+### Multi-Module Android Project
+
+```javascript
+export default {
+    channels: [{
+        source: new FsSource({ 
+            globs: [
+                'app/src/main/res/values/strings.xml',
+                'feature-*/src/main/res/values/strings.xml',
+                'library-*/src/main/res/values/strings.xml'
+            ]
+        }),
+        target: new FsTarget({ 
+            targetPath: (lang, resourceId) => {
+                // Handle different module structures
+                if (resourceId.includes('/values/')) {
+                    return resourceId.replace('/values/', `/values-${lang}/`);
+                }
+                return resourceId;
+            }
+        })
+    }]
+};
+```
+
+## File Structure Support
+
+L10n Monster supports standard Android resource directory structure:
+
+```
+app/src/main/res/
+├── values/              # Default (English) strings
+│   ├── strings.xml
+│   ├── plurals.xml
+│   └── arrays.xml
+├── values-es/           # Spanish translations
+│   └── strings.xml
+├── values-zh-rCN/       # Chinese (China) translations
+│   └── strings.xml
+└── values-b+es+419/     # Spanish (Latin America) - BCP 47
+    └── strings.xml
+```
+
+## Android-Specific Features
+
+### Placeholder Handling
+
+The helper properly handles Android string formatting:
+
+```xml
+<!-- Source -->
+<string name="welcome">Hello %1$s, you have %2$d messages</string>
+
+<!-- Maintains placeholder order and type -->
+<string name="welcome">Hola %1$s, tienes %2$d mensajes</string>
+```
+
+### Escape Sequence Processing
+
+```xml
+<!-- Input -->
+<string name="multiline">First line\nSecond line\tTabbed</string>
+
+<!-- Properly escaped output -->
+<string name="multiline">Primera línea\nSegunda línea\tTabulada</string>
+```
+
+### Plural Forms
+
+```xml
+<!-- Source -->
+<plurals name="items">
+    <item quantity="one">%d item</item>
+    <item quantity="other">%d items</item>
+</plurals>
+
+<!-- Translated with proper quantity handling -->
+<plurals name="items">
+    <item quantity="one">%d elemento</item>
+    <item quantity="other">%d elementos</item>
+</plurals>
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+The test suite covers:
+- XML parsing and generation
+- Escape sequence handling
+- Placeholder preservation
+- Plural form processing
+- Comment positioning
+- CDATA section handling
+
+## Integration with L10n Monster
+
+This helper integrates seamlessly with L10n Monster's provider system:
+
+```javascript
+import { providers } from '@l10nmonster/core';
+import { GptAgent } from '@l10nmonster/helpers-openai';
+
+export default {
+    providers: [{
+        id: 'ai-translator',
+        provider: new GptAgent({ 
+            model: 'gpt-4',
+            systemPrompt: 'Translate Android app strings, preserving all placeholders and formatting.'
+        })
+    }]
+};
+```
+
+## Requirements
+
+- Node.js >= 20.12.0
+- @l10nmonster/core (peer dependency)
+
+## Related Documentation
+
+- [Android String Resources](https://developer.android.com/guide/topics/resources/string-resource)
+- [Android Localization](https://developer.android.com/guide/topics/resources/localization)
+- [L10n Monster Core Documentation](../core/README.md)

package/filter.js

@@ -3,8 +3,9 @@
 // and preserve the source but the downside is that we miss automatic CDATA handling, whitespace trimming, entity management.
 // TODO: double quotes are meant to preserve newlines but we treat double quotes like CDATA (which doesn't)
 
-const { XMLParser, XMLBuilder } = require('fast-xml-parser');
-const xmlFormatter = require('xml-formatter');
+import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+import { default as formatXml } from 'xml-formatter';
+import { logVerbose } from '@l10nmonster/core';
 
 function collapseTextNodes(node) {
     return node.map(e => e['#text']).join('').trim();
@@ -16,11 +17,26 @@ function isTranslatableNode(resNode, str) {
     return resNode[':@'].translatable !== 'false' && !resNode[':@']['/'] && !resourceReferenceRegex.test(str);
 }
 
-module.exports = class AndroidFilter {
-    constructor({ indentation }) {
+/**
+ * Class representing an AndroidFilter for parsing and translating Android resource files.
+ */
+export class AndroidXMLFilter {
+
+    /**
+     * Create an AndroidXMLFilter.
+     * @param {Object} [options] - Configuration options for the filter.
+     * @param {string} [options.indentation='\t'] - The indentation character(s) to use in the output XML.
+     */
+    constructor({ indentation } = {}) {
         this.indentation = indentation || '\t';
     }
 
+    /**
+     * 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.
+     * @returns {Promise<Object>} An object containing the extracted segments.
+     */
     async parseResource({ resource }) {
         const segments = [];
         const parsingOptions = {
@@ -56,18 +72,22 @@ module.exports = class AndroidFilter {
                         }
                     } else if ('plurals' in resNode) { // TODO: support string-array
                         for (const itemNode of resNode.plurals) {
-                            const seg = {
-                                sid: `${resNode[':@'].name}_${itemNode[':@'].quantity}`,
-                                isSuffixPluralized: true,
-                                str: collapseTextNodes(itemNode.item)
-                            };
-                            lastComment && (seg.notes = lastComment);
-                            segments.push(seg);
+                            if ('#comment' in itemNode) {
+                                lastComment = itemNode['#comment'].map(e => e['#text']).join('').trim();
+                            } else if ('item' in itemNode) {
+                                const seg = {
+                                    sid: `${resNode[':@'].name}_${itemNode[':@'].quantity}`,
+                                    isSuffixPluralized: true,
+                                    str: collapseTextNodes(itemNode.item)
+                                };
+                                lastComment && (seg.notes = lastComment);
+                                segments.push(seg);
+                            }
                         }
                         lastComment = null;
                     } else {
-                        l10nmonster.logger.verbose(`Unexpected child node in resources`);
-                        l10nmonster.logger.verbose(JSON.stringify(resNode));
+                        logVerbose`Unexpected child node in resources`;
+                        logVerbose`${JSON.stringify(resNode)}`;
                     }
                 }
             }
@@ -77,6 +97,13 @@ module.exports = class AndroidFilter {
         };
     }
 
+    /**
+     * Translate an Android resource file using the provided translator function.
+     * @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.
+     * @returns {Promise<string|null>} The translated XML content, or null if no translations were made.
+     */
     async translateResource({ resource, translator }) {
         const parsingOptions = {
             ignoreAttributes: false,
@@ -113,7 +140,13 @@ module.exports = class AndroidFilter {
                         }
                     } else if ('plurals' in resNode) { // TODO: deal with plurals of the target language, not the source
                         let dropPlural = false;
+                        const itemNodesToDelete = []
                         for (const itemNode of resNode.plurals) {
+                            if ('#comment' in itemNode) {
+                                itemNodesToDelete.push(itemNode)
+                                // eslint-disable-next-line no-continue
+                                continue;
+                            }
                             const translation = await translator(`${resNode[':@'].name}_${itemNode[':@'].quantity}`, collapseTextNodes(itemNode.item));
                             if (translation === undefined) {
                                 dropPlural = true;
@@ -121,6 +154,7 @@ module.exports = class AndroidFilter {
                                 itemNode.item = [ { '#text': translation } ];
                             }
                         }
+                        resNode.plurals = resNode.plurals.filter(n => !itemNodesToDelete.includes(n))
                         if (dropPlural) {
                             nodesToDelete.push(resNode);
                         } else {
@@ -139,6 +173,6 @@ module.exports = class AndroidFilter {
         const builder = new XMLBuilder(parsingOptions);
         const roughXML = builder.build(parsedResource);
         // eslint-disable-next-line prefer-template
-        return xmlFormatter(roughXML, { collapseContent: true, indentation: this.indentation, lineSeparator: '\n' }) + '\n';
+        return formatXml(roughXML, { collapseContent: true, indentation: this.indentation, lineSeparator: '\n' }) + '\n';
     }
 }

package/index.js

@@ -1,12 +1,11 @@
-const { regex } = require('@l10nmonster/helpers');
-
-exports.Filter = require('./filter');
+import { regex } from '@l10nmonster/core';
+export { AndroidXMLFilter } from './filter.js';
 
 const androidControlCharsToDecode = {
     n: '\n',
     t: '\t',
 };
-exports.escapesDecoder = regex.decoderMaker(
+export const escapesDecoder = regex.decoderMaker(
     'androidEscapesDecoder',
     /(?<node>\\(?<escapedChar>[@?\\'"])|\\(?<escapedControl>[nt])|\\u(?<codePoint>[0-9A-Za-z]{4}))/g,
     (groups) => (groups.escapedChar ??
@@ -18,7 +17,7 @@ exports.escapesDecoder = regex.decoderMaker(
 );
 
 // Android lint doesn't accept % but accepts %%.  % should be replaced with '\u0025' but %% shouldn't
-exports.escapesEncoder = (str, flags = {}) => {
+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
     flags.isFirst && escapedStr[0] === ' ' && (escapedStr = '\\u0020' + escapedStr.substring(1));
@@ -27,10 +26,10 @@ exports.escapesEncoder = (str, flags = {}) => {
     return escapedStr;
 };
 
-exports.spaceCollapser = (parts) => parts.map(p => (p.t === 's' ? { ...p, v: p.v.replaceAll(/[ \f\n\r\t\v\u2028\u2029]+/g, ' ')} : p));
+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)
-exports.phDecoder = regex.decoderMaker(
+export const phDecoder = regex.decoderMaker(
     'iosPHDecoder',
     /(?<tag>%(?:\d\$)?[0#+-]?[0-9*]*\.?\d*[hl]{0,2}[jztL]?[diuoxXeEfgGaAcpsSn])/g,
     (groups) => ({ t: 'x', v: groups.tag })

package/package.json

@@ -1,18 +1,19 @@
 {
-  "name": "@l10nmonster/helpers-android",
-  "version": "1.0.0",
-  "description": "Helpers to deal with Android file formats",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "Diego Lagunas",
-  "license": "MIT",
-  "dependencies": {
-    "fast-xml-parser": "^4.0.3",
-    "xml-formatter": "^3"
-  },
-  "peerDependencies": {
-    "@l10nmonster/helpers": "^1"
-  }
+    "name": "@l10nmonster/helpers-android",
+    "version": "3.0.0-alpha.1",
+    "description": "Helpers to deal with Android file formats",
+    "type": "module",
+    "main": "index.js",
+    "scripts": {
+        "test": "node --test"
+    },
+    "author": "Diego Lagunas",
+    "license": "MIT",
+    "dependencies": {
+        "fast-xml-parser": "^5",
+        "xml-formatter": "^3"
+    },
+    "peerDependencies": {
+        "@l10nmonster/core": "file:../core"
+    }
 }