@l10nmonster/helpers-android 1.0.0

package/README.md

@@ -0,0 +1,18 @@
+# L10n Monster Android Helpers
+
+|Module|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.|
+
+
+```js
+this.resourceFilter = new android.Filter({
+    comment: 'pre',
+});
+```
+
+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).

package/filter.js

@@ -0,0 +1,144 @@
+// Check https://developer.android.com/guide/topics/resources/string-resource#FormattingAndStyling
+// Currently XML parsing is disabled for <string> and <item>. This is to make it easier to inject translations
+// 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');
+
+function collapseTextNodes(node) {
+    return node.map(e => e['#text']).join('').trim();
+}
+
+const resourceReferenceRegex=/^@(?:[0-9A-Za-z_$]+:)?[0-9A-Za-z_$]+\/[0-9A-Za-z_$]+$/;
+
+function isTranslatableNode(resNode, str) {
+    return resNode[':@'].translatable !== 'false' && !resNode[':@']['/'] && !resourceReferenceRegex.test(str);
+}
+
+module.exports = class AndroidFilter {
+    constructor({ indentation }) {
+        this.indentation = indentation || '\t';
+    }
+
+    async parseResource({ resource }) {
+        const segments = [];
+        const parsingOptions = {
+            ignoreAttributes: false,
+            processEntities: true,
+            htmlEntities: true,
+            allowBooleanAttributes: true,
+            alwaysCreateTextNode: true,
+            attributeNamePrefix : '',
+            commentPropName: "#comment",
+            preserveOrder: true,
+            stopNodes: ["*.string", "*.item"],
+            parseTagValue: false,
+            trimValues: true,
+        };
+        const parser = new XMLParser(parsingOptions);
+        for (const rootNode of parser.parse(resource)) {
+            if ('resources' in rootNode) {
+                let lastComment;
+                for (const resNode of rootNode.resources) {
+                    if ('#comment' in resNode) {
+                        lastComment = resNode['#comment'].map(e => e['#text']).join('').trim();
+                    } else if ('string' in resNode) {
+                        const str = collapseTextNodes(resNode.string);
+                        if (isTranslatableNode(resNode, str)) {
+                            const seg = {
+                                sid: resNode[':@'].name,
+                                str,
+                            };
+                            lastComment && (seg.notes = lastComment);
+                            segments.push(seg);
+                            lastComment = null;
+                        }
+                    } 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);
+                        }
+                        lastComment = null;
+                    } else {
+                        l10nmonster.logger.verbose(`Unexpected child node in resources`);
+                        l10nmonster.logger.verbose(JSON.stringify(resNode));
+                    }
+                }
+            }
+        }
+        return {
+            segments,
+        };
+    }
+
+    async translateResource({ resource, translator }) {
+        const parsingOptions = {
+            ignoreAttributes: false,
+            processEntities: true,
+            htmlEntities: true,
+            allowBooleanAttributes: true,
+            alwaysCreateTextNode: true,
+            attributeNamePrefix : '',
+            commentPropName: "#comment",
+            preserveOrder: true,
+            stopNodes: ["*.string", "*.item"],
+            parseTagValue: false,
+            trimValues: true,
+        };
+        const parser = new XMLParser(parsingOptions);
+        const parsedResource = parser.parse(resource);
+        const nodesToDelete = [];
+        let translated = 0;
+        for (const rootNode of parsedResource) {
+            if ('resources' in rootNode) {
+                for (const resNode of rootNode.resources) {
+                    if ('string' in resNode) {
+                        const str = collapseTextNodes(resNode.string);
+                        if (isTranslatableNode(resNode, str)) {
+                            const translation = await translator(resNode[':@'].name, str);
+                            if (translation === undefined) {
+                                nodesToDelete.push(resNode);
+                            } else {
+                                translated++;
+                                resNode.string = [ { '#text': translation } ];
+                            }
+                        } else {
+                            nodesToDelete.push(resNode);
+                        }
+                    } else if ('plurals' in resNode) { // TODO: deal with plurals of the target language, not the source
+                        let dropPlural = false;
+                        for (const itemNode of resNode.plurals) {
+                            const translation = await translator(`${resNode[':@'].name}_${itemNode[':@'].quantity}`, collapseTextNodes(itemNode.item));
+                            if (translation === undefined) {
+                                dropPlural = true;
+                            } else {
+                                itemNode.item = [ { '#text': translation } ];
+                            }
+                        }
+                        if (dropPlural) {
+                            nodesToDelete.push(resNode);
+                        } else {
+                            translated++;
+                        }
+                    } else {
+                        nodesToDelete.push(resNode); // drop other nodes because of https://github.com/NaturalIntelligence/fast-xml-parser/issues/435
+                    }
+                }
+                rootNode.resources = rootNode.resources.filter(n => !nodesToDelete.includes(n));
+            }
+        }
+        if (translated === 0) {
+            return null;
+        }
+        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';
+    }
+}

package/index.js

@@ -0,0 +1,37 @@
+const { regex } = require('@l10nmonster/helpers');
+
+exports.Filter = require('./filter');
+
+const androidControlCharsToDecode = {
+    n: '\n',
+    t: '\t',
+};
+exports.escapesDecoder = regex.decoderMaker(
+    'androidEscapesDecoder',
+    /(?<node>\\(?<escapedChar>[@?\\'"])|\\(?<escapedControl>[nt])|\\u(?<codePoint>[0-9A-Za-z]{4}))/g,
+    (groups) => (groups.escapedChar ??
+        (groups.escapedControl ?
+            (androidControlCharsToDecode[groups.escapedControl] ?? `\\${groups.escapedControl}`) :
+            String.fromCharCode(parseInt(groups.codePoint, 16))
+        )
+    )
+);
+
+// Android lint doesn't accept % but accepts %%.  % should be replaced with '\u0025' but %% shouldn't
+exports.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));
+    // eslint-disable-next-line prefer-template
+    flags.isLast && escapedStr.length > 0 && escapedStr[escapedStr.length - 1] === ' ' && (escapedStr = escapedStr.substring(0, escapedStr.length - 1) + '\\u0020');
+    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));
+
+// C-style placeholders (based on the ios one)
+exports.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

@@ -0,0 +1,18 @@
+{
+  "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"
+  }
+}