@esgettext/runtime 1.1.0 → 1.2.0

package/LICENSE

@@ -1,4 +1,4 @@
-This software is Copyright (C) 2020 by Guido Flohr.
+This software is Copyright (C) 2020-2024 by Guido Flohr.
 
 This is free software, licensed under:
 

package/README.md

@@ -6,22 +6,22 @@ GNU gettext-alike translation runtime library.
 
 - [API Documentation](#api-documentation)
 - [Internationalizing Hello World](#internationalizing-hello-world)
-  - [Choosing a Textdomain](#choosing-a-textdomain)
-  - [Install the Library](#install-the-library)
-  - [Import the Library](#import-the-library)
-  - [Prepare Your Sources](#prepare-your-sources)
-  - [Translation Methods](#translation-methods)
-    - [Simple Translations With `_()`](#simple-translations-with-_)
-    - [Variable Interpolation With `_x()`](#variable-interpolation-with-_x)
-    - [Plural Forms With `_nx()`](#plural-forms-with-_nx)
-    - [Message Context With `_p()`](#message-context-with-_p)
-    - [Specific Locale with `_l`](#specific-locale-with-_l)
-    - [TODO: Gender-Specific Translations](#todo-gender-specific-translations)
-  - [Selecting the Preferred Language with `selectLocale()`](#selecting-the-preferred-language-with-selectlocale)
+	- [Choosing a Textdomain](#choosing-a-textdomain)
+	- [Install the Library](#install-the-library)
+	- [Import the Library](#import-the-library)
+	- [Prepare Your Sources](#prepare-your-sources)
+	- [Translation Methods](#translation-methods)
+		- [Simple Translations With `_()`](#simple-translations-with-_)
+		- [Variable Interpolation With `_x()`](#variable-interpolation-with-_x)
+		- [Plural Forms With `_nx()`](#plural-forms-with-_nx)
+		- [Message Context With `_p()`](#message-context-with-_p)
+		- [Specific Locale with `_l`](#specific-locale-with-_l)
+		- [TODO: Gender-Specific Translations](#todo-gender-specific-translations)
+	- [Selecting the Preferred Language with `selectLocale()`](#selecting-the-preferred-language-with-selectlocale)
 - [Internationalizing a Library](#internationalizing-a-library)
 - [Frequently-Asked Questions](#frequently-asked-questions)
-  - [Why do Template Strings not Work?](#why-do-template-strings-not-work)
-  - [What Does the Error "template literals with embedded expressions are not allowed as arguments to gettext functions because they are not constant" Mean?](#what-does-the-error-template-literals-with-embedded-expressions-are-not-allowed-as-arguments-to-gettext-functions-because-they-are-not-constant-mean)
+	- [Why do Template Strings not Work?](#why-do-template-strings-not-work)
+	- [What Does the Error "template literals with embedded expressions are not allowed as arguments to gettext functions because they are not constant" Mean?](#what-does-the-error-template-literals-with-embedded-expressions-are-not-allowed-as-arguments-to-gettext-functions-because-they-are-not-constant-mean)
 - [Copyright](#copyright)
 
 ## API Documentation
@@ -82,7 +82,7 @@ $ yarn add @esgettext/runtime
 
 How to import the library, depends on your environment.
 
-If you have the `import` keyword:
+If you have the `import` keyword (TypeScript or ES module syntax):
 
 ```javascript
 import { Textdomain } from '@esgettext/runtime';
@@ -91,11 +91,9 @@ import { Textdomain } from '@esgettext/runtime';
 If you can use `require`:
 
 ```javascript
-const esgettext = require('@esgettext/runtime');
-const Textdomain = esgettext.Textdomain;
+const { Textdomain } = require('@esgettext/runtime');
 ```
 
-_FIXME! Is this correct?_
 
 If you are writing javascript loaded by a browser:
 
@@ -404,7 +402,7 @@ template string with interpolated expressions.
 
 ## Copyright
 
-Copyright (C) 2020 Guido Flohr <guido.flohr@cantanea.com>, all
+Copyright (C) 2020-2024 Guido Flohr <guido.flohr@cantanea.com>, all
 rights reserved.
 
 This software is available under the terms and conditions of the

package/dist/core/catalog-cache.d.ts

@@ -5,6 +5,17 @@ export declare class CatalogCache {
     private constructor();
     static getInstance(): CatalogCache;
     static clear(): void;
+    /**
+     * 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: string, textdomain: string): Catalog | Promise<Catalog> | null;
     static store(localeKey: string, textdomain: string, entry: Catalog | Promise<Catalog>): void;
 }

package/dist/core/catalog-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-cache.d.ts","sourceRoot":"","sources":["../../src/core/catalog-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBpC,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAA6B;IAEjD,OAAO;IAIP,MAAM,CAAC,WAAW,IAAI,YAAY;IAQlC,MAAM,CAAC,KAAK,IAAI,IAAI;WAeN,MAAM,CACnB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;WAWtB,KAAK,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/B,IAAI;CAWP"}
+{"version":3,"file":"catalog-cache.d.ts","sourceRoot":"","sources":["../../src/core/catalog-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBpC,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAA6B;IAEjD,OAAO;IAIP,MAAM,CAAC,WAAW,IAAI,YAAY;IAQlC,MAAM,CAAC,KAAK,IAAI,IAAI;IAIpB;;;;;;;;;;OAUG;WACW,MAAM,CACnB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;WAWtB,KAAK,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/B,IAAI;CAWP"}

package/dist/core/catalog.d.ts

@@ -1,10 +1,48 @@
-export interface CatalogEntries {
+/**
+ * The set of translations found in a [[`Catalog`]].
+ *
+ * This interface is used internally. You will only need it if you want to
+ * write your own message retrieval method or want to inspect a loaded
+ * [[`Catalog`]].
+ *
+ * The translations are looked up by their singular form in the original
+ * language. The value is an array of strings. The first item is the singular
+ * translation, the optional following items are the plural forms.
+ *
+ * If a translation has a message context, the key is the context joined
+ * with the translation by a `'\u0004'` character. For example, the key for
+ * the msgid "Open" with the msgctxt "Menu|File" would be `Menu|File\u0004Open`.
+ */
+export type CatalogEntries = {
     [key: string]: Array<string>;
-}
-export interface Catalog {
+};
+/**
+ * A [[`Catalog`]] is a container for a set of translations loaded from a
+ * `mo.json` or a binary `.mo` file.
+ *
+ * This interface is used internally. You will only need it if you want to
+ * write your own message retrieval method or want to inspect a loaded
+ * [[`Catalog`]].
+ */
+export type Catalog = {
+    /** The major revision number of the catalog, currently always 0. */
     major: number;
+    /** The minor revision number of the catalog, currently always 0 or 1. */
     minor: number;
+    /**
+     * Compute the index of a plural form from a number of items. If a language
+     * has one singular and two plural forms, the singular form would have
+     * index 0 and the plural forms have index 1 and 2.
+     *
+     * The plural function would then compute one of 0, 1, or 2 from an
+     * arbitrary non-negative integer.
+     *
+     * @param numItems - the number of items.
+     *
+     * @returns the index of the plural form.
+     */
     pluralFunction(numItems: number): number;
+    /** The actual translations. */
     entries: CatalogEntries;
-}
+};
 //# sourceMappingURL=catalog.d.ts.map

package/dist/core/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/core/catalog.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAUD,MAAM,WAAW,OAAO;IAEvB,KAAK,EAAE,MAAM,CAAC;IAGd,KAAK,EAAE,MAAM,CAAC;IAcd,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAGzC,OAAO,EAAE,cAAc,CAAC;CACxB"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/core/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG;IACrB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IAEd,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzC,+BAA+B;IAC/B,OAAO,EAAE,cAAc,CAAC;CACxB,CAAC"}

package/dist/core/data-viewlet.d.ts

@@ -3,7 +3,17 @@ export declare class DataViewlet {
     private decoder;
     private _encoding;
     constructor(array: Uint8Array, encoding?: string);
+    /**
+     * Get the encoding for strings.
+     *
+     * @returns the encoding in use
+     */
     get encoding(): string;
+    /**
+     * Switch to a new encoding.
+     *
+     * @param encoding - new encoding to use
+     */
     set encoding(encoding: string);
     readUInt32BE(offset?: number): number;
     readUInt32LE(offset?: number): number;

package/dist/core/data-viewlet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-viewlet.d.ts","sourceRoot":"","sources":["../../src/core/data-viewlet.ts"],"names":[],"mappings":"AAIA,qBAAa,WAAW;IAYtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAXvB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAUR,KAAK,EAAE,UAAU,EAClC,QAAQ,SAAU;IAWnB,IAAI,QAAQ,IAAI,MAAM,CAErB;IAOD,IAAI,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAG5B;IAUD,YAAY,CAAC,MAAM,SAAI,GAAG,MAAM;IAuBhC,YAAY,CAAC,MAAM,SAAI,GAAG,MAAM;IAqBhC,UAAU,CAAC,MAAM,SAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;CAc/C"}
+{"version":3,"file":"data-viewlet.d.ts","sourceRoot":"","sources":["../../src/core/data-viewlet.ts"],"names":[],"mappings":"AAIA,qBAAa,WAAW;IAYtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAXvB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAUR,KAAK,EAAE,UAAU,EAClC,QAAQ,SAAU;IAMnB;;;;OAIG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;OAIG;IACH,IAAI,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAG5B;IAUD,YAAY,CAAC,MAAM,SAAI,GAAG,MAAM;IAuBhC,YAAY,CAAC,MAAM,SAAI,GAAG,MAAM;IAqBhC,UAAU,CAAC,MAAM,SAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;CAc/C"}

package/dist/core/locale-container.d.ts

@@ -1,9 +1,32 @@
-import { Catalog } from './catalog';
-export interface LocaleContainer {
+import type { Catalog } from './catalog';
+/**
+ * An object storing locale information.  It resembles the directory structure
+ * that [[`Catalog`]] objects are found in.
+ *
+ * Example, if your textdomain is 'myapp':
+ *
+ * <pre class="language-javascript"><code class="language-javascript">\{
+ *         fr: \{
+ *                 LC_MESSAGES: \{
+ * 	                       myapp: catalogs['fr']
+ *                 \}
+ *         \},
+ *         'de-DE': \{
+ *                 LC_MESSAGES: \{
+ *                         myapp: catalogs['de-DE']
+ *                 \}
+ *         \}
+ * \}
+ * </code></pre>
+ */
+export type LocaleContainer = {
+    /** A language code like 'fr' or 'de-DE'. */
     [key: string]: {
+        /** The Locale category, always 'LC_MESSAGES'. */
         [key: string]: {
+            /** The textdomain. */
             [key: string]: Catalog;
         };
     };
-}
+};
 //# sourceMappingURL=locale-container.d.ts.map

package/dist/core/locale-container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale-container.d.ts","sourceRoot":"","sources":["../../src/core/locale-container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,MAAM,WAAW,eAAe;IAE/B,CAAC,GAAG,EAAE,MAAM,GAAG;QAEd,CAAC,GAAG,EAAE,MAAM,GAAG;YAEd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;SACvB,CAAC;KACF,CAAC;CACF"}
+{"version":3,"file":"locale-container.d.ts","sourceRoot":"","sources":["../../src/core/locale-container.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,4CAA4C;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG;QACd,iDAAiD;QACjD,CAAC,GAAG,EAAE,MAAM,GAAG;YACd,sBAAsB;YACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;SACvB,CAAC;KACF,CAAC;CACF,CAAC"}

package/dist/core/resolve-impl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-impl.d.ts","sourceRoot":"","sources":["../../src/core/resolve-impl.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAKpD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAiPrD,wBAAgB,WAAW,CAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GAAG,eAAe,EAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAyBlB"}
+{"version":3,"file":"resolve-impl.d.ts","sourceRoot":"","sources":["../../src/core/resolve-impl.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAKpD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AA4MrD,wBAAsB,WAAW,CAChC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GAAG,eAAe,EAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAiBlB"}