@esgettext/runtime 1.1.0 → 1.2.0

package/dist/esgettext.esm.js

@@ -1,6 +1,14 @@
 import { readFile } from 'fs';
 
 let userLocalesSelected = ['C'];
+/*
+ * Force an execution environment. By default, the environment (NodeJS or
+ * browser) is auto-detected. You can force the library to assume a certain
+ * environment with this function.
+ *
+ * @param browser - whether to assume a browser or not
+ * @returns the new setting.
+ */
 function userLocales(locales) {
     if (typeof locales !== 'undefined') {
         userLocalesSelected = locales;
@@ -8,6 +16,39 @@ function userLocales(locales) {
     return userLocalesSelected;
 }
 
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol */
+
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
 class TransportHttp {
     loadFile(url) {
         return new Promise((resolve, reject) => {
@@ -38,23 +79,60 @@ class TransportFs {
     }
 }
 
+/*
+ * Function for germanic plural. Returns singular (0) for 1 item, and
+ * 1 for everything else.
+ *
+ * @param numItems - number of items
+ * @returns the index into the plural translations
+ */
 function germanicPlural(numItems) {
     return numItems === 1 ? 0 : 1;
 }
 
+/*
+ * A minimalistic buffer implementation that can only read 32 bit unsigned
+ * integers and strings.
+ */
 class DataViewlet {
+    /*
+     * Create a DataViewlet instance. All encodings that are supported by
+     * the runtime environments `TextDecoder` interface.
+     *
+     * @param array - a `Unit8Array` view on the binary buffer
+     * @param encoding - encoding of strings, defaults to utf-8
+     */
     constructor(array, encoding = 'utf-8') {
         this.array = array;
         this.decoder = new TextDecoder(encoding);
         this._encoding = encoding;
     }
+    /**
+     * Get the encoding for strings.
+     *
+     * @returns the encoding in use
+     */
     get encoding() {
         return this._encoding;
     }
+    /**
+     * Switch to a new encoding.
+     *
+     * @param encoding - new encoding to use
+     */
     set encoding(encoding) {
         this.decoder = new TextDecoder(encoding);
         this._encoding = encoding;
     }
+    /*
+     * Reads an unsigned 32-bit integer from the buffer at
+     * the specified offset as big-endian.
+     *
+     * @param offset - Number of bytes to skip before starting to read.
+     *                 Must satisfy `0 <= offset <= buf.length - 4`.
+     *                 Default: 0.
+     * @returns the 32-bit unsigned integer at position `offset`.s
+     */
     readUInt32BE(offset = 0) {
         if (offset + 4 > this.array.byteLength + this.array.byteOffset) {
             throw new Error('read past array end');
@@ -65,6 +143,15 @@ class DataViewlet {
             this.array[offset + 3]) >>>
             0);
     }
+    /*
+     * Reads an unsigned 32-bit integer from the buffer at
+     * the specified offset as little-endian.
+     *
+     * @param offset - Number of bytes to skip before starting to read.
+     *                 Must satisfy `0 <= offset <= buf.length - 4`.
+     *                 Default: 0.
+     * @returns the 32-bit unsigned integer at position `offset`.s
+     */
     readUInt32LE(offset = 0) {
         if (offset + 4 > this.array.byteLength + this.array.byteOffset) {
             throw new Error('read past array end');
@@ -75,6 +162,13 @@ class DataViewlet {
             this.array[offset]) >>>
             0);
     }
+    /*
+     * Read a string at a specified offset.
+     *
+     * @param offset - to beginning of buffer in bytes
+     * @param length - of the string to read in bytes or to the end of the
+     *                 buffer if not specified.
+     */
     readString(offset = 0, length) {
         if (offset + length >
             this.array.byteLength + this.array.byteOffset) {
@@ -87,6 +181,15 @@ class DataViewlet {
     }
 }
 
+/*
+ * Parse an MO file.
+ *
+ * An exception is thrown for invalid data.
+ *
+ * @param raw - The input as either a binary `String`, any `Array`-like byte
+ *              storage (`Array`, `Uint8Array`, `Arguments`, `jQuery(Array)`, ...)
+ * @returns a Catalog
+ */
 function parseMoCatalog(raw) {
     const catalog = {
         major: 0,
@@ -99,15 +202,19 @@ function parseMoCatalog(raw) {
     const magic = blob.readUInt32LE(offset);
     let reader;
     if (magic === 0x950412de) {
+        /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
         reader = (buf, off) => buf.readUInt32LE(off);
     }
     else if (magic === 0xde120495) {
+        /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
         reader = (buf, off) => buf.readUInt32BE(off);
     }
     else {
         throw new Error(`invalid MO magic 0x${magic.toString(16)}`);
     }
     offset += 4;
+    // The revision is encoded in two shorts, major and minor.  We don't care
+    // about the minor revision.
     const major = reader(blob, offset) >> 16;
     offset += 4;
     if (major > 0) {
@@ -168,6 +275,10 @@ function parseMoCatalog(raw) {
 }
 
 function validateMoJsonCatalog(udata) {
+    // We could use ajv but it results in almost 300 k minimized code
+    // for the browser bundle. This validator instead is absolutely
+    // minimalistic, and only avoids exceptions that can occur, when
+    // accessing entries.
     if (udata === null || typeof udata === 'undefined') {
         throw new Error('catalog is either null or undefined');
     }
@@ -175,6 +286,8 @@ function validateMoJsonCatalog(udata) {
     if (data.constructor !== Object) {
         throw new Error('catalog must be a dictionary');
     }
+    // We don't care about major and minor because they are actually not
+    // used.
     if (!Object.prototype.hasOwnProperty.call(data, 'entries')) {
         throw new Error('catalog.entries does not exist');
     }
@@ -199,11 +312,16 @@ function parseMoJsonCatalog(json) {
 }
 
 function validateJsonCatalog(udata) {
+    // We could use ajv but it results in almost 300 k minimized code
+    // for the browser bundle. This validator instead is absolutely
+    // minimalistic, and only avoids exceptions that can occur, when
+    // accessing entries.
     if (udata === null || typeof udata === 'undefined') {
         throw new Error('catalog is either null or undefined');
     }
     const entries = udata;
     if (entries.constructor !== Object) ;
+    // Convert to a regular catalog.
     const catalog = {
         major: 0,
         minor: 1,
@@ -211,6 +329,7 @@ function validateJsonCatalog(udata) {
         entries: {},
     };
     for (const [msgid, msgstr] of Object.entries(entries)) {
+        // Just stringify all values but do not complain.
         catalog.entries[msgid] = [msgstr.toString()];
     }
     return catalog;
@@ -256,8 +375,19 @@ function splitLocale(locale) {
     return split;
 }
 
+/*
+ * Caches catalog lookups by path, locale, and textdomain.
+ *
+ * Failed lookups are stored as null values.
+ *
+ * It is also possible to store a Promise. In that case, if a request is
+ * made to bind the textdomain, the promise is settled. Note that this
+ * mechanism is never used for message lookup but only for loading the
+ * catalog via resolve.
+ */
 class CatalogCache {
     constructor() {
+        /* Singleton. */
     }
     static getInstance() {
         if (!CatalogCache.instance) {
@@ -268,6 +398,17 @@ class CatalogCache {
     static clear() {
         CatalogCache.cache = {};
     }
+    /**
+     * Lookup a Catalog for a given base path, locale, and textdomain.
+     *
+     * The locale key is usually the locale identifier (e.g. de-DE or sr\@latin).
+     * But it can also be a colon separated list of such locale identifiers.
+     *
+     *
+     * @param localeKey - the locale key
+     * @param textdomain - the textdomain
+     * @returns the cached Catalog, a Promise or null for failure
+     */
     static lookup(localeKey, textdomain) {
         if (CatalogCache.cache[localeKey]) {
             const ptr = CatalogCache.cache[localeKey];
@@ -279,6 +420,7 @@ class CatalogCache {
     }
     static store(localeKey, textdomain, entry) {
         if (Promise.resolve(entry) !== entry) {
+            // Object.
             entry = validateMoJsonCatalog(entry);
         }
         if (!CatalogCache.cache[localeKey]) {
@@ -320,144 +462,141 @@ function explodeLocale(locale, vary) {
 }
 
 function loadCatalog(url, format) {
-    let transportInstance;
-    {
-        let transport;
-        try {
-            const parsedURL = new URL(url);
-            if (parsedURL.protocol === 'https:' ||
-                parsedURL.protocol === 'http:' ||
-                parsedURL.protocol === 'file:') {
-                transport = 'http';
+    return __awaiter(this, void 0, void 0, function* () {
+        let transportInstance;
+        {
+            let transport;
+            // Check whether this is a valid URL.
+            try {
+                const parsedURL = new URL(url);
+                if (parsedURL.protocol === 'https:' ||
+                    parsedURL.protocol === 'http:' ||
+                    parsedURL.protocol === 'file:') {
+                    transport = 'http';
+                }
+                else {
+                    throw new Error(`unsupported scheme ${parsedURL.protocol}`);
+                }
+            }
+            catch (e) {
+                {
+                    transport = 'fs';
+                }
+            }
+            if (transport === 'http') {
+                transportInstance = new TransportHttp();
             }
             else {
-                throw new Error(`unsupported scheme ${parsedURL.protocol}`);
+                transportInstance = new TransportFs();
             }
         }
-        catch (e) {
-            {
-                transport = 'fs';
-            }
+        let validator;
+        if ('mo.json' === format) {
+            validator = parseMoJsonCatalog;
         }
-        if (transport === 'http') {
-            transportInstance = new TransportHttp();
+        else if ('.json' === format) {
+            validator = parseJsonCatalog;
         }
         else {
-            transportInstance = new TransportFs();
+            validator = parseMoCatalog;
+        }
+        try {
+            const data = yield transportInstance.loadFile(url);
+            return validator(data);
+        }
+        catch (_a) {
+            return null;
         }
-    }
-    let validator;
-    if ('mo.json' === format) {
-        validator = parseMoJsonCatalog;
-    }
-    else if ('.json' === format) {
-        validator = parseJsonCatalog;
-    }
-    else {
-        validator = parseMoCatalog;
-    }
-    return new Promise((resolve, reject) => {
-        transportInstance
-            .loadFile(url)
-            .then(data => {
-            resolve(validator(data));
-        })
-            .catch(e => reject(e));
     });
 }
 function assemblePath(base, id, domainname, extender) {
     return `${base}/${id}/LC_MESSAGES/${domainname}.${extender}`;
 }
 function loadLanguageFromObject(ids, base, domainname) {
-    let catalog;
-    for (let i = 0; i < ids.length; ++i) {
-        const id = ids[0];
-        if (!Object.prototype.hasOwnProperty.call(base, id)) {
-            continue;
-        }
-        if (!Object.prototype.hasOwnProperty.call(base[id], 'LC_MESSAGES')) {
-            continue;
-        }
-        if (!Object.prototype.hasOwnProperty.call(base[id].LC_MESSAGES, domainname)) {
-            continue;
-        }
-        catalog = base[id].LC_MESSAGES[domainname];
-    }
-    return new Promise((resolve, reject) => {
-        if (catalog) {
-            resolve(catalog);
-        }
-        else {
-            reject();
+    return __awaiter(this, void 0, void 0, function* () {
+        for (let i = 0; i < ids.length; ++i) {
+            const id = ids[i];
+            // Language exists?
+            if (!Object.prototype.hasOwnProperty.call(base, id)) {
+                continue;
+            }
+            // LC_MESSAGES?
+            if (!Object.prototype.hasOwnProperty.call(base[id], 'LC_MESSAGES')) {
+                continue;
+            }
+            // Textdomain?
+            if (!Object.prototype.hasOwnProperty.call(base[id].LC_MESSAGES, domainname)) {
+                continue;
+            }
+            return base[id].LC_MESSAGES[domainname];
         }
+        return null;
     });
 }
-async function loadLanguage(ids, base, domainname, format) {
-    if (typeof base === 'object' && base !== null) {
-        return loadLanguageFromObject(ids, base, domainname);
-    }
-    return new Promise((resolve, reject) => {
-        const tries = new Array();
-        ids.forEach(id => {
-            tries.push(() => loadCatalog(assemblePath(base, id, domainname, format), format));
-        });
-        tries
-            .reduce((promise, fn) => promise.catch(fn), Promise.reject())
-            .then(value => resolve(value))
-            .catch(e => reject(e));
+/*
+ * First tries to load a catalog with the specified charset, then with the
+ * charset converted to uppercase (if it differs from the original charset),
+ * and finally without a charset.
+ */
+function loadLanguage(ids, base, domainname, format) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Check if `base` is an object (LocaleContainer).
+        if (typeof base === 'object' && base !== null) {
+            return loadLanguageFromObject(ids, base, domainname);
+        }
+        for (const id of ids) {
+            const catalog = yield loadCatalog(assemblePath(base, id, domainname, format), format);
+            if (catalog) {
+                return catalog;
+            }
+        }
+        return null;
     });
 }
-async function loadDomain(exploded, localeKey, base, domainname, format) {
-    const entries = {};
-    const catalog = {
-        major: 0,
-        minor: 0,
-        pluralFunction: germanicPlural,
-        entries,
-    };
-    const cacheHit = CatalogCache.lookup(localeKey, domainname);
-    if (cacheHit !== null) {
-        if (Promise.resolve(cacheHit) === cacheHit) {
+function loadDomain(exploded, localeKey, base, domainname, format) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const entries = {};
+        const catalog = {
+            major: 0,
+            minor: 0,
+            pluralFunction: germanicPlural,
+            entries,
+        };
+        const cacheHit = yield CatalogCache.lookup(localeKey, domainname);
+        if (cacheHit !== null) {
             return cacheHit;
         }
-        else {
-            return new Promise(resolve => resolve(cacheHit));
+        for (const tries of exploded) {
+            const result = yield loadLanguage(tries, base, domainname, format);
+            if (result) {
+                catalog.major = result.major;
+                catalog.minor = result.minor;
+                catalog.entries = Object.assign(Object.assign({}, catalog.entries), result.entries);
+            }
         }
-    }
-    const promises = new Array();
-    const results = new Array();
-    exploded.forEach((tries, i) => {
-        const p = loadLanguage(tries, base, domainname, format)
-            .then(catalog => (results[i] = catalog))
-            .catch(() => {
-        });
-        promises.push(p);
-    });
-    await Promise.all(promises);
-    results.forEach(result => {
-        catalog.major = result.major;
-        catalog.minor = result.minor;
-        catalog.entries = Object.assign(Object.assign({}, catalog.entries), result.entries);
-    });
-    return new Promise(resolve => {
-        resolve(catalog);
+        return catalog;
     });
 }
 function pluralExpression(str) {
     const tokens = str
         .replace(/[ \t\r\013\014]/g, '')
         .replace(/;$/, '')
+        // Do NOT allow square brackets here. JSFuck!
         .split(/[<>!=]=|&&|\|\||[-!*/%+<>=?:;]/);
     for (let i = 0; i < tokens.length; ++i) {
         const token = tokens[i].replace(/^\(+/, '').replace(/\)+$/, '');
         if (token !== 'nplurals' &&
             token !== 'plural' &&
             token !== 'n' &&
+            // Does not catch invalid octal numbers but the compiler
+            // takes care of that.
             null === /^[0-9]+$/.exec(token)) {
             throw new Error('invalid plural function');
         }
     }
     const code = 'var nplurals = 1, plural = 0;' + str + '; return 0 + plural';
+    // This may throw an exception!
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
     return new Function('n', code);
 }
 function setPluralFunction(catalog) {
@@ -469,33 +608,32 @@ function setPluralFunction(catalog) {
         const tokens = header.split(':');
         if ('plural-forms' === tokens.shift().toLowerCase()) {
             const code = tokens.join(':');
-            catalog.pluralFunction = pluralExpression(code);
+            try {
+                catalog.pluralFunction = pluralExpression(code);
+            }
+            catch (_a) {
+                catalog.pluralFunction = germanicPlural;
+            }
         }
     });
     return catalog;
 }
 function resolveImpl(domainname, path, format, localeKey) {
-    const defaultCatalog = {
-        major: 0,
-        minor: 0,
-        pluralFunction: germanicPlural,
-        entries: {},
-    };
-    if (localeKey === 'C' || localeKey === 'POSIX') {
-        return new Promise(resolve => resolve(defaultCatalog));
-    }
-    return new Promise(resolve => {
+    return __awaiter(this, void 0, void 0, function* () {
+        const defaultCatalog = {
+            major: 0,
+            minor: 0,
+            pluralFunction: germanicPlural,
+            entries: {},
+        };
+        if (localeKey === 'C' || localeKey === 'POSIX') {
+            return defaultCatalog;
+        }
         const exploded = explodeLocale(splitLocale(localeKey));
-        loadDomain(exploded, localeKey, path, domainname, format)
-            .then(catalog => {
-            setPluralFunction(catalog);
-            CatalogCache.store(localeKey, domainname, catalog);
-            resolve(catalog);
-        })
-            .catch(() => {
-            CatalogCache.store(localeKey, domainname, defaultCatalog);
-            resolve(defaultCatalog);
-        });
+        const catalog = yield loadDomain(exploded, localeKey, path, domainname, format);
+        setPluralFunction(catalog);
+        CatalogCache.store(localeKey, domainname, catalog);
+        return catalog;
     });
 }
 
@@ -575,10 +713,50 @@ function selectLocale(supported, requested) {
     return 'C';
 }
 
+/**
+ * A Textdomain is a container for an esgettext configuration and all loaded
+ * LocaleContainer for the textual domain selected.
+ *
+ * The actual translation methods have quite funny names like `_()` or
+ * `_x()`. The purpose of this naming convention is to make the
+ * internationalization of your programs as little obtrusive as possible.
+ * Most of the times you just have to exchange
+ *
+ * ```
+ * doSomething('Hello, world!');
+ * ```
+ *
+ * with
+ *
+ * ```
+ * doSomething(gtx._('Hello, world!'));
+ * ```
+ *
+ * Besides, depending on the string extractor you are using, it may be useful
+ * that the method names do not collide with method names from other packages.
+ */
 class Textdomain {
+    /**
+     * Retrieve a translation for a string.
+     *
+     * @param msgid - the string to translate
+     *
+     * @returns the translated string
+     */
     _(msgid) {
         return gettextImpl({ msgid: msgid, catalog: this.catalog });
     }
+    /**
+     * Retrieve a translation for a string containing a possible plural.
+     * You will almost always want to call {@link _nx} instead so that
+     * you can interpolate the number of items into the strings.
+     *
+     * @param msgid - the string in the singular
+     * @param msgidPlural - the string in the plural
+     * @param numItems - the number of items
+     *
+     * @returns the translated string
+     */
     _n(msgid, msgidPlural, numItems) {
         return gettextImpl({
             msgid: msgid,
@@ -587,6 +765,14 @@ class Textdomain {
             catalog: this.catalog,
         });
     }
+    /**
+     * Translate a string with a context.
+     *
+     * @param msgctxt - the message context
+     * @param msgid - the string to translate
+     *
+     * @returns the translated string
+     */
     _p(msgctxt, msgid) {
         return gettextImpl({
             msgctxt: msgctxt,
@@ -594,6 +780,17 @@ class Textdomain {
             catalog: this.catalog,
         });
     }
+    /**
+     * The method `_np()` combines `_n()` with `_p()`.
+     * You will almost always want to call {@link _npx} instead so that
+     * you can interpolate the number of items into the strings.
+
+     *
+     * @param msgctxt - the message context
+     * @param msgid - the message id
+     * @param placeholders - a dictionary with placehoders
+     * @returns the translated string
+     */
     _np(msgctxt, msgid, msgidPlural, numItems) {
         return gettextImpl({
             msgctxt: msgctxt,
@@ -603,9 +800,29 @@ class Textdomain {
             catalog: this.catalog,
         });
     }
+    /**
+     * Translate a string with placeholders. The placeholders should be
+     * wrapped into curly braces and must match the regular expression
+     * "[_a-zA-Z][_a-zA-Z0-9]*".
+     *
+     * @param msgid - the msgid to translate
+     * @param placeholders - an optional dictionary of placeholders
+     *
+     * @returns the translated string with placeholders expanded
+     */
     _x(msgid, placeholders) {
         return Textdomain.expand(gettextImpl({ msgid: msgid, catalog: this.catalog }), placeholders || {});
     }
+    /**
+     * Translate a string with a plural expression with placeholders.
+     *
+     * @param msgid - the string in the singular
+     * @param msgidPlural - the string in the plural
+     * @param numItems - the number of items
+     * @param placeholders - an optional dictionary of placeholders
+     *
+     * @returns the translated string
+     */
     _nx(msgid, msgidPlural, numItems, placeholders) {
         return Textdomain.expand(gettextImpl({
             msgid: msgid,
@@ -614,9 +831,28 @@ class Textdomain {
             catalog: this.catalog,
         }), placeholders || {});
     }
+    /**
+     * The method `_px()` combines `_p()` with `_x()`.
+     *
+     * @param msgctxt - the message context
+     * @param msgid - the message id
+     * @param placeholders - an optional dictionary with placehoders
+     * @returns the translated string
+     */
     _px(msgctxt, msgid, placeholders) {
         return Textdomain.expand(gettextImpl({ msgctxt: msgctxt, msgid: msgid, catalog: this.catalog }), placeholders || {});
     }
+    /**
+     * The method `_npx()` brings it all together. It combines `_n()` and
+     * `_p()` and `_x()`.
+     *
+     * @param msgctxt - the message context
+     * @param msgid - the message id
+     * @param msgidPlural - the plural string
+     * @param numItems - the number of items
+     * @param placeholders - an optional dictionary with placehoders
+     * @returns the translated string
+     */
     _npx(msgctxt, msgid, msgidPlural, numItems, placeholders) {
         return Textdomain.expand(gettextImpl({
             msgctxt: msgctxt,
@@ -638,10 +874,31 @@ class Textdomain {
         }
         return catalog;
     }
+    /**
+     * Retrieve a translation for a string with a fixed locale.
+     *
+     * @param locale - the locale identifier
+     * @param msgid - the string to translate
+     *
+     * @returns the translated string
+     */
     _l(locale, msgid) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return gettextImpl({ msgid: msgid, catalog: catalog });
     }
+    /**
+     * Retrieve a translation for a string containing a possible plural with
+     * a fixed locale.
+     * You will almost always want to call {@link _nx} instead so that
+     * you can interpolate the number of items into the strings.
+     *
+     * @param locale - the locale identifier
+     * @param msgid - the string in the singular
+     * @param msgidPlural - the string in the plural
+     * @param numItems - the number of items
+     *
+     * @returns the translated string
+     */
     _ln(locale, msgid, msgidPlural, numItems) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return gettextImpl({
@@ -651,10 +908,31 @@ class Textdomain {
             catalog: catalog,
         });
     }
+    /**
+     * Translate a string with a context with a fixed locale.
+     *
+     * @param locale - the locale identifier
+     * @param msgctxt - the message context
+     * @param msgid - the string to translate
+     *
+     * @returns the translated string
+     */
     _lp(locale, msgctxt, msgid) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return gettextImpl({ msgctxt: msgctxt, msgid: msgid, catalog: catalog });
     }
+    /**
+     * The method `_lnp()` combines `_ln()` with `_lp()`.
+     * You will almost always want to call {@link _npx} instead so that
+     * you can interpolate the number of items into the strings.
+
+     *
+     * @param locale - the locale identifier
+     * @param msgctxt - the message context
+     * @param msgid - the message id
+     * @param placeholders - a dictionary with placehoders
+     * @returns the translated string
+     */
     _lnp(locale, msgctxt, msgid, msgidPlural, numItems) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return gettextImpl({
@@ -665,10 +943,34 @@ class Textdomain {
             catalog: catalog,
         });
     }
+    /**
+     * Translate a string with placeholders for a fixed locale.
+     * The placeholders should be
+     * wrapped into curly braces and must match the regular expression
+     * "[_a-zA-Z][_a-zA-Z0-9]*".
+     *
+     * @param locale - the locale identifier
+     * @param msgid - the msgid to translate
+     * @param placeholders - an optional dictionary of placeholders
+     *
+     * @returns the translated string with placeholders expanded
+     */
     _lx(locale, msgid, placeholders) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return Textdomain.expand(gettextImpl({ msgid: msgid, catalog: catalog }), placeholders || {});
     }
+    /**
+     * Translate a string with a plural expression with placeholders into a
+     * fixed locale.
+     *
+     * @param locale - the locale identifier
+     * @param msgid - the string in the singular
+     * @param msgidPlural - the string in the plural
+     * @param numItems - the number of items
+     * @param placeholders - an optional dictionary of placeholders
+     *
+     * @returns the translated string
+     */
     _lnx(locale, msgid, msgidPlural, numItems, placeholders) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return Textdomain.expand(gettextImpl({
@@ -678,10 +980,31 @@ class Textdomain {
             catalog: catalog,
         }), placeholders || {});
     }
+    /**
+     * The method `_lpx()` combines `_lp()` with `_lx()`.
+     *
+     * @param locale - the locale identifier
+     * @param msgctxt - the message context
+     * @param msgid - the message id
+     * @param placeholders - an optional dictionary with placehoders
+     * @returns the translated string
+     */
     _lpx(locale, msgctxt, msgid, placeholders) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return Textdomain.expand(gettextImpl({ msgctxt: msgctxt, msgid: msgid, catalog: catalog }), placeholders || {});
     }
+    /**
+     * The method `_lnpx()` brings it all together. It combines `_ln()` and
+     * `_lp()` and `_lx()`.
+     *
+     * @param locale - the locale identifier
+     * @param msgctxt - the message context
+     * @param msgid - the message id
+     * @param msgidPlural - the plural string
+     * @param numItems - the number of items
+     * @param placeholders - an optional dictionary with placehoders
+     * @returns the translated string
+     */
     _lnpx(locale, msgctxt, msgid, msgidPlural, numItems, placeholders) {
         const catalog = Textdomain.getCatalog(locale, this.textdomain());
         return Textdomain.expand(gettextImpl({
@@ -702,6 +1025,14 @@ class Textdomain {
             }
         });
     }
+    /**
+     * Instantiate a Textdomain object. Textdomain objects are singletons
+     * for each textdomain identifier.
+     *
+     * @param textdomain - the textdomain of your application or library.
+     *
+     * @returns a [[`Textdomain`]]
+     */
     static getInstance(textdomain) {
         if (typeof textdomain === 'undefined' ||
             textdomain === null ||
@@ -723,16 +1054,49 @@ class Textdomain {
             return domain;
         }
     }
+    /**
+     * Delete all existing singletons. This method should usually be called
+     * only, when you want to free memory.
+     */
     static clearInstances() {
         Textdomain.boundDomains = {};
     }
+    /**
+     * This method is used for testing.  Do not use it yourself!
+     */
     static forgetInstances() {
         Textdomain.clearInstances();
         Textdomain.domains = {};
     }
+    /**
+     * Query the locale in use.
+     */
     static get locale() {
         return Textdomain._locale;
     }
+    /**
+     * Change the locale.
+     *
+     * For the web you can use all valid language identifier tags that
+     * [BCP47](https://tools.ietf.org/html/bcp47) allows
+     * (and actually a lot more). The tag is always used unmodified.
+     *
+     * For server environments, the locale identifier has to match the following
+     * scheme:
+     *
+     *   `ll_CC.charset\@modifier`
+     *
+     * * `ll` is the two- or three-letter language code.
+     * * `CC` is the optional two-letter country code.
+     * * `charset` is an optional character set (letters, digits, and the hyphen).
+     * * `modifier` is an optional variant (letters and digits).
+     *
+     * The language code is always converted to lowercase, the country code is
+     * converted to uppercase, variant and charset are used as is.
+     *
+     * @param locale - the locale identifier
+     * @returns the locale in use
+     */
     static set locale(locale) {
         const ucLocale = locale.toUpperCase();
         if (ucLocale === 'POSIX' || ucLocale === 'C') {
@@ -743,6 +1107,7 @@ class Textdomain {
         if (!split) {
             throw new Error('invalid locale identifier');
         }
+        // Node.
         split.tags[0] = split.tags[0].toLowerCase();
         if (split.tags.length > 1) {
             split.tags[1] = split.tags[1].toUpperCase();
@@ -758,46 +1123,110 @@ class Textdomain {
     }
     constructor(domain) {
         this._catalogFormat = 'mo.json';
+        this.catalog = undefined;
         this.domain = domain;
+        const msg = "The property 'locale' is not an instance property but static. Use 'Textdomain.locale' instead!";
+        Object.defineProperty(this, 'locale', {
+            get: () => {
+                throw new Error(msg);
+            },
+            set: () => {
+                throw new Error(msg);
+            },
+            enumerable: true,
+            configurable: true,
+        });
     }
+    /**
+     * A textdomain is an identifier for your application or library. It is
+     * the basename of your translation files which are either
+     * TEXTDOMAIN.mo.json or TEXTDOMAIN.mo, depending on the format you have
+     * chosen.
+     *
+     * FIXME! This should be a getter!
+     *
+     * @returns the textdomain
+     */
     textdomain() {
         return this.domain;
     }
+    /**
+     * Bind a textdomain to a certain path or queries the path that a
+     * textdomain is bound to. The catalog file will be searched
+     * in `${path}/LC_MESSAGES/${domainname}.EXT` where `EXT` is the
+     * selected catalog format (one of `mo.json`, `mo`, or `json`).
+     *
+     * Alternatively, you can pass a [[`LocaleContainer`]] that holds the
+     * catalogs in memory.
+     *
+     * The returned string or `LocaleContainer` is valid until the next
+     * `bindtextdomain` call with an argument.
+     *
+     * @param path - the base path or [[`LocaleContainer`]] for this textdomain
+     *
+     * @returns the current base directory or [[`LocaleContainer`]] for this domain, after possibly changing it.
+     */
     bindtextdomain(path) {
         if (typeof path !== 'undefined') {
             Textdomain.boundDomains[this.domain] = path;
         }
         return Textdomain.boundDomains[this.domain];
     }
-    async resolve(locale) {
-        const promises = [this.resolve1(locale)];
-        for (const td in Textdomain.domains) {
-            if (Object.prototype.hasOwnProperty.call(Textdomain.domains, td) &&
-                Textdomain.domains[td] !== this) {
-                promises.push(Textdomain.domains[td].resolve1(locale));
+    /**
+     * Resolve a textdomain, i.e. load the LocaleContainer for this domain and all
+     * of its dependencies for the currently selected locale or the locale
+     * specified.
+     *
+     * The promise will always resolve. If no catalog was found, an empty
+     * catalog will be returned that is still usable.
+     *
+     * @param locale - an optional locale identifier, defaults to Textdomain.locale
+     *
+     * @returns a promise for a Catalog that will always resolve.
+     */
+    resolve(locale) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const promises = [this.resolve1(locale)];
+            for (const td in Textdomain.domains) {
+                if (Object.prototype.hasOwnProperty.call(Textdomain.domains, td) &&
+                    Textdomain.domains[td] !== this) {
+                    promises.push(Textdomain.domains[td].resolve1(locale));
+                }
             }
-        }
-        return Promise.all(promises).then(values => {
-            return new Promise(resolve => resolve(values[0]));
+            return Promise.all(promises).then(values => {
+                return new Promise(resolve => resolve(values[0]));
+            });
         });
     }
-    async resolve1(locale) {
-        let path = this.bindtextdomain();
-        if (typeof path === 'undefined' || path === null) {
-            const parts = ['.', 'locale'];
-            path = parts.join(pathSeparator);
-        }
-        const resolvedLocale = locale ? locale : Textdomain.locale;
-        return resolveImpl(this.domain, path, this.catalogFormat, resolvedLocale).then(catalog => {
-            if (!locale) {
-                this.catalog = catalog;
+    resolve1(locale) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let path = this.bindtextdomain();
+            if (typeof path === 'undefined' || path === null) {
+                const parts = ['.', 'locale'];
+                path = parts.join(pathSeparator);
             }
-            return new Promise(resolve => resolve(catalog));
+            const resolvedLocale = locale ? locale : Textdomain.locale;
+            return resolveImpl(this.domain, path, this.catalogFormat, resolvedLocale).then(catalog => {
+                if (!locale) {
+                    this.catalog = catalog;
+                }
+                return new Promise(resolve => resolve(catalog));
+            });
         });
     }
+    /**
+     * Get the catalog format in use.
+     *
+     * @returns one of 'mo.json' or 'mo' (default is 'mo.json')
+     */
     get catalogFormat() {
         return this._catalogFormat;
     }
+    /**
+     * Set the catalog format to use.
+     *
+     * @param format - one of 'mo.json' or 'mo'
+     */
     set catalogFormat(format) {
         format = format.toLowerCase();
         if (format === 'mo.json') {
@@ -810,42 +1239,156 @@ class Textdomain {
             throw new Error(`unsupported format ${format}`);
         }
     }
+    /**
+     * Queries the user's preferred locales. On the server it queries the
+     * environment variables `LANGUAGE`, `LC_ALL`, `LANG`, and `LC_MESSAGES`
+     * (in that order). In the browser, it parses it checks the user preferences
+     * in the variables `navigator.languages`, `navigator.language`,
+     * `navigator.userLanguage`, `navigator.browserLanguage`, and
+     * `navigator.systemLanguage`.
+     *
+     * @returns the set of locales in order of preference
+     *
+     * Added in \@runtime 0.1.0.
+     */
     static userLocales() {
         return userLocales();
     }
+    /**
+     * Select one of the supported locales from a list of locales accepted by
+     * the user.
+     *
+     * @param supported - the list of locales supported by the application
+     * @param requested - the list of locales accepted by the user
+     *
+     * If called with just one argument, then the list of requested locales
+     * is determined by calling [[Textdomain.userLocales]].
+     *
+     * @returns the negotiated locale or 'C' if not possible.
+     */
     static selectLocale(supported, requested) {
         return selectLocale(supported, requested !== null && requested !== void 0 ? requested : Textdomain.userLocales());
     }
+    /**
+     * A no-op method for string marking.
+     *
+     * Sometimes you want to mark strings for translation but do not actually
+     * want to translate them, at least not at the time of their definition.
+     * This is often the case, when you have to preserve the original string.
+     *
+     * Take this example:
+     *
+     * ```
+     * orangeColors = [gtx.N_('coral'), gtx.N_('tomato'), gtx.N_('orangered'),
+     *                 gtx.N_('gold'), gtx.N_('orange'), gtx.N_('darkorange')]
+     * ```
+     *
+     * These are standard CSS colors, and you cannot translate them inside
+     * CSS styles. But for presentation you may want to translate them later:
+     *
+     * ```
+     * console.log(gtx._x("The css color '{color}' is {translated}.",
+     *                    {
+     *                        color: orangeColors[2],
+     *                        translated: gtx._(orangeColors[2]),
+     *                    }
+     *            )
+     * );
+     * ```
+     *
+     * In other words: The method just marks strings for translation, so that
+     * the extractor `esgettext-xgettext` finds them but it does not actually
+     * translate anything.
+     *
+     * Similar methods are available for other cases (with placeholder
+     * expansion, context, or both). They are *not* available for plural
+     * methods because that would not make sense.
+     *
+     * Note that all of these methods are also available as instance methods.
+     *
+     * @param msgid - the message id
+     * @returns the original string
+     */
     static N_(msgid) {
         return msgid;
     }
+    /**
+     * Does the same as the static method `N_()`.
+     *
+     * @param msgid - the message id
+     * @returns the original string
+     */
     N_(msgid) {
         return msgid;
     }
+    /**
+     * Same as `N_()` but with placeholder expansion.
+     *
+     * @param msgid - the message id
+     * @param placeholders - a dictionary of placeholders
+     * @returns the original string with placeholders expanded
+     */
     N_x(msgid, placeholders) {
         return Textdomain.expand(msgid, placeholders !== null && placeholders !== void 0 ? placeholders : {});
     }
+    /**
+     * Does the same as the static method `N_x()`.
+     *
+     * @param msgid - the message id
+     * @param placeholders - a dictionary of placeholders
+     * @returns the original string with placeholders expanded
+     */
     static N_x(msgid, placeholders) {
         return Textdomain.expand(msgid, placeholders !== null && placeholders !== void 0 ? placeholders : {});
     }
+    /**
+     * Same as `N_()` but with context.
+     *
+     * @param _msgctxt - the message context (not used)
+     * @param msgid - the message id
+     * @returns the original string
+     */
     N_p(_msgctxt, msgid) {
         return msgid;
     }
+    /**
+     * Does the same as the static method `N_p()`.
+     *
+     * @param _msgctxt - the message context (not used)
+     * @param msgid - the message id
+     * @returns the original string with placeholders expanded
+     */
     static N_p(_msgctxt, msgid) {
         return msgid;
     }
+    /**
+     * Same as `N_()` but with context and placeholder expansion.
+     *
+     * @param _msgctxt - the message context (not used)
+     * @param msgid - the message id
+     * @param placeholders - a dictionary of placeholders
+     * @returns the original string with placeholders expanded
+     */
     N_px(_msgctxt, msgid, placeholders) {
         return Textdomain.expand(msgid, placeholders !== null && placeholders !== void 0 ? placeholders : {});
     }
+    /**
+     * Does the same as the static method `N_px()`.
+     *
+     * @param _msgctxt - the message context (not used)
+     * @param msgid - the message id
+     * @param placeholders - a dictionary of placeholders
+     * @returns the original string with placeholders expanded
+     */
     static N_px(_msgctxt, msgid, placeholders) {
         return Textdomain.expand(msgid, placeholders !== null && placeholders !== void 0 ? placeholders : {});
     }
 }
 Textdomain.domains = {};
-Textdomain.cache = CatalogCache.getInstance();
 Textdomain.boundDomains = {};
 Textdomain._locale = 'C';
 
+// FIXME! Windows!
 if (typeof process.env.LANGUAGE !== 'undefined') {
     userLocales(process.env.LANGUAGE.split(':'));
 }