ilib-tools-common 1.2.0 → 1.4.0

package/src/TranslationUnit.js

@@ -0,0 +1,178 @@
+/*
+ * TranslationUnit.js - model a translation unit in a translation file
+ *
+ * Copyright © 2023 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import log4js from "@log4js-node/log4js-api";
+
+import TranslationVariant from './TranslationVariant.js';
+import { hashKey } from './utils.js';
+
+const logger = log4js.getLogger("tools-common.TranslationUnit");
+
+/**
+ * @class Represent a translation unit. A translation unit is
+ * a segment in the source language, along with one or
+ * more variants, which are translations to various
+ * target languages. A translation unit may contain more
+ * than one translation for a particular locale, as there
+ * are sometimes more than one translation for a particular
+ * phrase in the source language, depending on the context.
+ */
+class TranslationUnit {
+    /**
+     * Create a new translation unit.
+     *
+     * The options may be undefined, which represents
+     * a new, clean TranslationUnit instance. The options object may also
+     * be an object with the following properties:
+     *
+     * <ul>
+     * <li><i>source</i> - source text for this unit (required)
+     * <li><i>sourceLocale</i> - the source locale spec for this unit (required)
+     * <li><i>target</i> - target text for this unit (optional)
+     * <li><i>targetLocale</i> - the target locale spec for this unit (optional)
+     * <li><i>key</i> - the unique resource key for this translation unit (required)
+     * <li><i>file</i> - path to the original source code file that contains the
+     * source text of this translation unit (required)
+     * <li><i>project</i> - the project that this string/unit is part of
+     * <li><i>resType</i> - type of this resource (string, array, plural) (optional)
+     * <li><i>state</i> - the state of the current unit (optional)
+     * <li><i>comment</i> - the translator's comment for this unit (optional)
+     * <li><i>datatype</i> - the source of the data of this unit (optional)
+     * <li><i>flavor</i> - the flavor that this string comes from(optional)
+     * </ul>
+     *
+     * If the required properties are not given, the constructor throws an exception.<p>
+     *
+     * For newly extracted strings, there is no target text yet. There must be a target
+     * locale for the translators to use when creating new target text, however. This
+     * means that there may be multiple translation units in a file with the same
+     * source locale and no target text, but different target locales.
+     *
+     * @param {Object} options options for this unit
+     */
+    constructor(options) {
+//        this.locale = options.locale;      -> sourceLocale
+//        this.string = options.string;      -> source
+//        this.datatype = options.datatype;  -> datatype
+
+        this.variants = [];
+        this.variantHash = {};
+        this.properties = {};
+
+        if (options) {
+            const requiredFields = ["source", "sourceLocale"];
+            const missing = requiredFields.filter(p => {
+                if (typeof(options[p]) !== "undefined") {
+                    this[p] = options[p];
+                    return false;
+                }
+                return true;
+            });
+            // logger.trace("options is " + JSON.stringify(options));
+            if (missing.length) {
+                throw new Error("Missing required parameters in the TranslationUnit constructor: " + missing.join(", "));
+            }
+
+            const otherFields = ["key", "file", "project", "target", "targetLocale", "resType", "state", "comment", "datatype", "flavor"];
+            for (var p of otherFields) {
+                this[p] = options[p];
+            }
+        }
+    }
+
+    /**
+     * Clone the current unit and return the clone.
+     * @returns {TranslationUnit} a clone of the current unit.
+     */
+    clone() {
+        return new TranslationUnit(this);
+    }
+
+    /**
+     * Return a unique hash key for this translation unit. The
+     * hash key is calculated from the source string and locale
+     * and does not depend on the properties or variants in
+     * the unit.
+     *
+     * @returns {string} the unique hash key
+     */
+    hashKey() {
+        return [hashKey(this.source), this.sourceLocale, this.datatype].join("_");
+    }
+
+    /**
+     * Return the list of variants for this translation unit.
+     * @returns {Array.<TranslationVariant>} the variants for
+     * this translation unit
+     */
+    getVariants() {
+        return this.variants;
+    }
+
+    /**
+     * Add a single variant to this translation unit. This variant
+     * is only added if it is unique in this translation unit. That is,
+     * No other variant exists in this unit with the same locale and
+     * string.
+     *
+     * @param {TranslationVariant} variant the variant to add
+     */
+    addVariant(variant) {
+        var key = variant.hashKey();
+        if (!this.variantHash[key]) {
+            this.variants.push(variant);
+            this.variantHash[key] = variant;
+        }
+    }
+
+    /**
+     * Add an array of variants to this translation unit. This only
+     * adds a variant if it is unique. That is, the unit is not
+     * added if the locale and string are the same as an existing
+     * variant.
+     *
+     * @param {Array.<TranslationVariant>} variants the array of variants to add
+     */
+    addVariants(variants) {
+        variants.forEach(variant => {
+            this.addVariant(variant);
+        });
+    }
+
+    /**
+     * Return the list of properties and their values for this translation unit.
+     * @returns {Object} an object mapping properties to values
+     */
+    getProperties() {
+        return this.properties;
+    }
+
+    /**
+     * Add a property to this translation unit.
+     * @param {Object} properties an object that maps properties to values
+     */
+    addProperties(properties) {
+        for (let p in properties) {
+            if (properties[p]) {
+                this.properties[p] = properties[p];
+            }
+        }
+    }
+}
+
+export default TranslationUnit;

package/src/TranslationVariant.js

@@ -0,0 +1,51 @@
+/*
+ * TranslationVariant.js - model a translation variant in a translation file
+ *
+ * Copyright © 2023 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { hashKey } from './utils.js';
+
+/**
+ * @class A class that represents a translation unit variant.
+ */
+class TranslationVariant {
+    /**
+     * Options may contain the following properties:
+     * - locale: locale of the target string
+     * - string: the translation for this locale
+     *
+     * @param {Object} options
+     */
+    constructor(options) {
+        if (options) {
+            this.locale = options.locale;
+            this.string = options.string;
+        }
+    }
+
+    /**
+     * Return a unique hash key for this translation unit variant. The
+     * hash key is calculated from the source string and locale.
+     *
+     * @returns {string} the unique hash key
+     */
+    hashKey() {
+        return [hashKey(this.string), this.locale].join("_");
+    }
+}
+
+export default TranslationVariant;

package/src/index.js

@@ -23,7 +23,17 @@ import ResourceArray from './ResourceArray.js';
 import ResourcePlural from './ResourcePlural.js';
 import TranslationSet from './TranslationSet.js';
 import ResourceXliff from './ResourceXliff.js';
-import { formatPath, getLocaleFromPath } from './utils.js';
+import TranslationUnit from './TranslationUnit.js';
+import TranslationVariant from './TranslationVariant.js';
+import {
+    formatPath,
+    getLocaleFromPath,
+    cleanString,
+    isEmpty,
+    makeDirs,
+    containsActualText,
+    objectMap
+} from './utils.js';
 
 export {
     Resource,
@@ -31,7 +41,14 @@ export {
     ResourceArray,
     ResourcePlural,
     TranslationSet,
+    TranslationUnit,
+    TranslationVariant,
     ResourceXliff,
     formatPath,
-    getLocaleFromPath
+    getLocaleFromPath,
+    cleanString,
+    isEmpty,
+    makeDirs,
+    containsActualText,
+    objectMap
 };

package/src/utils.js

@@ -1,7 +1,7 @@
 /*
  * utils.js - utility functions to support the other code
  *
- * Copyright © 2022 JEDLSoft
+ * Copyright © 2022-2023 JEDLSoft
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,9 +17,12 @@
  * limitations under the License.
  */
 
+import fs from 'node:fs';
 import path from 'node:path';
 import Locale from 'ilib-locale';
 
+import { isAlnum, isIdeo } from 'ilib-ctype';
+
 /**
  * Clean a string for matching against other strings by removing
  * differences that are inconsequential for translation.
@@ -312,3 +315,90 @@ export function getLocaleFromPath(template, pathname) {
 
     return "";
 };
+
+export function makeDirs(path) {
+    const parts = path.split(/[\\\/]/);
+
+    for (let i = 1; i <= parts.length; i++) {
+        const p = parts.slice(0, i).join("/");
+        if (p && p.length > 0 && !fs.existsSync(p)) {
+            fs.mkdirSync(p);
+        }
+    }
+};
+
+/**
+ * Return true if the string still contains some text after removing all HTML tags and entities.
+ * @param {string} str the string to check
+ * @returns {boolean} true if there is text left over, and false otherwise
+ */
+export function containsActualText(str) {
+    // remove the html and entities first
+    const cleaned = str.replace(/<("(\\"|[^"])*"|'(\\'|[^'])*'|[^>])*>/g, "").replace(/&[a-zA-Z]+;/g, "");
+
+    for (let i = 0; i < cleaned.length; i++) {
+        const c = cleaned.charAt(i);
+        if (isAlnum(c) || isIdeo(c)) return true;
+    }
+    return false;
+};
+
+function isPrimitive(type) {
+    return ["boolean", "number", "integer", "string"].indexOf(type) > -1;
+}
+
+/**
+ * Recursively visit every node in an object and call the visitor on any
+ * primitive values.
+ * @param {*} object any object, arrary, or primitive
+ * @param {Function(*)} visitor function to call on any primitive
+ * @returns {*} the same type as the original object, but with every
+ * primitive processed by the visitor function
+ */
+export function objectMap(object, visitor) {
+    if (!object) return object;
+    if (isPrimitive(typeof(object))) {
+        return visitor(object);
+    } else if (Array.isArray(object)) {
+        return object.map(item => {
+            return objectMap(item, visitor);
+        });
+    } else {
+        const ret = {};
+        for (let prop in object) {
+            if (object.hasOwnProperty(prop)) {
+                ret[prop] = objectMap(object[prop], visitor);
+            }
+        }
+        return ret;
+    }
+};
+
+/**
+ * Return a standard hash of the given source string.
+ *
+ * @param {String} source the source string as extracted from the
+ * source code, unmodified
+ * @returns {String} the hash key
+ */
+export function hashKey(source) {
+    if (!source) return undefined;
+    let hash = 0;
+    // these two numbers together = 46 bits so it won't blow out the precision of an integer in javascript
+    const modulus = 1073741789;  // largest prime number that fits in 30 bits
+    const multiple = 65521;      // largest prime that fits in 16 bits, co-prime with the modulus
+
+    // logger.trace("hash starts off at " + hash);
+
+    for (let i = 0; i < source.length; i++) {
+        // logger.trace("hash " + hash + " char " + source.charCodeAt(i) + "=" + source.charAt(i));
+        hash += source.charCodeAt(i);
+        hash *= multiple;
+        hash %= modulus;
+    }
+    const value = "r" + hash;
+
+    // System.out.println("String '" + source + "' hashes to " + value);
+
+    return value;
+};