@itrocks/translate 0.2.2 → 0.2.4

package/README.md

@@ -6,7 +6,7 @@
 
 # translate
 
-Manage dynamic string translations with support for variables and composite patterns.
+Translate English source strings with small, language-specific CSV catalogs.
 
 *This documentation was written by an artificial intelligence and may contain errors or approximations.
 It has not yet been fully reviewed by a human. If anything seems unclear or incomplete,
@@ -18,281 +18,110 @@ please feel free to contact the author of this package.*
 npm i @itrocks/translate
 ```
 
-This package has a runtime dependency on `papaparse`, which is installed automatically
-as a transitive dependency when you install `@itrocks/translate`.
-
 ## Usage
 
-`@itrocks/translate` provides a tiny in-memory translation engine for Node.js.
-
-You typically use it to:
-
-- declare the current UI language with `trInit()`,
-- load translation keys from a CSV file with `trLoad()`,
-- translate strings at runtime with `tr()`,
-- optionally inspect or extend the in-memory `translations` map.
-
-The focus is on **dynamic translations of small text snippets** (labels, button
-texts, messages) with support for:
-
-- automatic case handling (uppercasing the first letter),
-- placeholders like `$1`, `$2`, ... replaced by runtime values,
-- composite expressions that can themselves contain expressions.
-
-### Minimal example
-
-```ts
-import { tr, trInit, trLoad } from '@itrocks/translate'
-
-async function main() {
-  // 1. Select the language and reset internal state
-  trInit('en-US')
-
-  // 2. Load translations from a ;‑separated CSV file
-  await trLoad('locales/en-US.csv')
-
-  // 3. Translate a simple key
-  console.log(tr('hello'))          // e.g. "Hello"
-
-  // 4. Translate a key with placeholders
-  console.log(tr('welcome.user.$1', ['John'])) // e.g. "Welcome, John"
-}
+Translation sources stay in English. Each semicolon-separated CSV file maps them to one language:
 
-main().catch(console.error)
+```csv
+hello;bonjour
+private: $1 recipients;privée : $1 destinataires
 ```
 
-### Complete example with composite patterns
+Catalog entries are context-free fragments: start both columns with a lowercase letter unless the word requires a
+capital, and keep sentence-separating periods in the caller rather than at either end of a CSV value. The translator
+restores an initial capital and translates each period-separated fragment independently.
 
-`tr()` can both translate **simple keys** and **composite expressions**. Composite
-expressions are translated by splitting them around punctuation and translating
-each part separately while preserving spaces.
+An isolated `:` or `;` entry may translate to the same separator prefixed with a space when a target language requires
+different spacing. The caller still owns the separator itself.
 
-You can also store patterns with placeholders in the translation file. When a
-pattern matches the source text, `tr()` automatically:
-
-- translates each captured part,
-- appends the translated parts to the `parts` array,
-- and reuses them to build the final translated string.
+Initialize the default language and load every translated catalog once:
 
 ```ts
-import { expressions, lang, tr, trInit, trLoad, translations } from '@itrocks/translate'
-
-async function initTranslations() {
-  // Initialize the language (any BCP 47 code string is accepted)
-  trInit('fr-FR')
+import { tr, trInit, trLoad, trReverse, trWithLanguage } from '@itrocks/translate'
 
-  // Load a ;‑separated CSV file with two columns: source;translation
-  // Example content:
-  // hello;Bonjour
-  // "Hello, $1";"Bonjour, $1"
-  // "You have $1 new messages";"Vous avez $1 nouveaux messages"
-  await trLoad('locales/fr-FR.csv')
+trInit('en-US')
+await trLoad('locales/fr-FR.csv', 'fr-FR')
 
-  console.log('Current language:', lang())
-
-  console.log(tr('hello'))                 // "Bonjour"
-  console.log(tr('Hello, $1', ['Marie']))  // "Bonjour, Marie"
-  console.log(tr('You have $1 new messages', ['3']))
-  // => "Vous avez 3 nouveaux messages"
-
-  // The underlying maps are available if you need to inspect or extend them
-  console.log('Loaded translations:', translations.size)
-  console.log('Expression patterns:', expressions.size)
-}
-
-initTranslations().catch(console.error)
+await trWithLanguage('fr-FR', async () => {
+  console.log(tr('Hello'))                           // Bonjour
+  console.log(tr('Private: $1 recipients.', ['2'])) // Privée : 2 destinataires.
+  console.log(trReverse('Bonjour'))                  // Hello
+})
 ```
 
-> **Note**
-> This package is intentionally minimal: it does not manage locales, fallbacks,
-> or pluralization rules on its own. Those concerns are expected to be handled
-> by your application or higher‑level framework.
+The asynchronous language context is isolated between concurrent requests. A language with no catalog, such as the
+English source language above, leaves source strings unchanged.
 
 ## API
 
-### `DefaultOptions`
-
-```ts
-export const DefaultOptions: Options
-```
-
-The default options used by `tr()` when no explicit `options` are provided.
-
-Currently only one option is defined:
-
-- `ucFirst: boolean` (default `true`): when `true`, if the input text starts
-  with an uppercase ASCII letter (`A`–`Z`), the translated string is forced to
-  start with an uppercase letter as well.
-
-You can override this behavior per call using the `options` argument of `tr()`.
-
-### `expressions`
+### `lang()`
 
 ```ts
-export const expressions: Set<RegExp>
+function lang(): string
 ```
 
-The set of **compiled expression patterns** used for advanced matching in `tr()`.
-
-You normally do not need to modify this set manually. It is populated by
-`trLoad()` when a source key in the CSV file contains placeholders like `$1`.
+Returns the language of the current asynchronous context, or the default language set by `trInit()`.
 
-Each such key generates a regular expression that is later used by `tr()` to
-match dynamic sentences and extract sub‑parts for translation.
-
-### `translations`
+### `tr()`
 
 ```ts
-export const translations: Map<string, string>
+function tr(text: string, options: Options): string
+function tr(text: string, parts?: string[], options?: Options): string
 ```
 
-The in‑memory translation dictionary. Keys are **source texts** (usually
-English strings or stable identifiers), and values are their translated
-counterparts in the currently active language.
+Translates `text` with the current language catalog. It supports `$1`, `$2`, … placeholders, preserves surrounding
+spaces and can match catalog sources containing placeholders. If no translation exists, it returns the source text.
 
-This map is cleared each time you call `trInit()`. It is filled by `trLoad()`
-and can be extended or inspected manually if needed.
-
-### `type Options`
+When `ucFirst` is enabled, an uppercase source initial also produces an uppercase translated initial:
 
 ```ts
 export type Options = {
   ucFirst?: boolean
 }
-```
 
-Additional options that can be passed to `tr()`:
-
-- `ucFirst` (default: `DefaultOptions.ucFirst`): whether the first character of
-  the translated string should be uppercased when the original first character
-  is an uppercase ASCII letter.
+export const DefaultOptions: Options = {
+  ucFirst: true
+}
+```
 
-### `lang()`
+### `trInit()`
 
 ```ts
-function lang(): string
+function trInit(language: string): void
 ```
 
-Returns the **current language code** previously set with `trInit()`.
+Sets the default language and clears all previously loaded catalogs. Call it once before loading catalogs.
 
-The package does not interpret the value: you can use any string (for example
-`'en-US'`, `'fr-FR'`, `'de'`), as long as it is meaningful to your
-application.
-
-### `tr()`
+### `trLoad()`
 
 ```ts
-// Overload 1: no parts array, only options
-function tr(text: string, options: Options): string
-
-// Overload 2: explicit parts and optional options
-function tr(text: string, parts?: string[], options?: Options): string
+function trLoad(file: string, language?: string): Promise<void | unknown>
 ```
 
-Translates the given `text` using the current `translations` map and returns
-the translated string.
-
-Behavior details:
-
-1. **Spacing preservation** – leading and trailing whitespace in `text` are
-   preserved around the translated content.
-2. **Lookup strategy** – for the trimmed `text`, `tr()` looks up, in order:
-   - an exact match in `translations`,
-   - if `ucFirst` is enabled and the first character is uppercase, the same key
-     but with the first letter lower‑cased,
-   - the lower‑cased key,
-   - a match from expression patterns in `expressions` (see `trLoad()`).
-3. **Composite sentences** – if no translation is found, `tr()` looks for a
-   punctuation separator (`.?!;:,()`). When found, the text is split around the
-   first such separator, each part is translated separately with `tr()`, and the
-   final string is reassembled while preserving spaces (including non‑breaking
-   spaces around the separator).
-4. **Fallback** – if no translation or expression match is found, the original
-   trimmed text is returned.
-5. **Placeholders** – if a `parts` array is provided, elements are substituted
-   into the translated string by replacing `$1`, `$2`, ... from the end of the
-   array backwards.
-
-Usage patterns:
-
-```ts
-tr('hello')
-tr('Hello', { ucFirst: false })
-tr('welcome.$1', ['John'])
-tr('You have $1 new messages', ['3'])
-```
+Loads a UTF-8, semicolon-separated `source;translation` file into `language`. The language defaults to the one passed
+to `trInit()`. A missing file is ignored so applications can look for catalogs in several module directories.
 
-### `trInit()`
+### `trReverse()`
 
 ```ts
-function trInit(lang: string): void
+function trReverse(text: string): string
 ```
 
-Initializes or switches the current language. This function:
-
-- sets the internal language code returned by `lang()`,
-- clears all previously loaded `translations`,
-- clears all compiled `expressions`.
+Looks for a translated value in the current language catalog and returns its English source, accepting an initial
+capital added by `tr()`. If none matches, it returns `text` unchanged. This is intended for occasional input
+normalization, such as converting a translated code entered in a search field back to the code stored in English. It
+reads the current catalog backwards on demand; no reverse catalog is loaded or retained.
 
-Call this once per language at application startup, or whenever you change the
-active language and want to reload translation data.
-
-### `trLoad()`
+### `trWithLanguage()`
 
 ```ts
-async function trLoad(file: string): Promise<void | unknown>
+function trWithLanguage<T>(language: string, callback: () => T): T
 ```
 
-Loads translations from a **semicolon‑separated CSV file** at the given path.
-
-Behavior:
-
-- If the file does not exist or cannot be accessed, the function simply
-  returns without throwing.
-- It reads the file as UTF‑8 and parses it using `papaparse` with `;` as the
-  delimiter.
-- Each row is expected to have at least two columns: `row[0]` is the source
-  string, `row[1]` is the translated string. Extra columns are ignored.
-- For each row, the pair is stored in `translations`.
-- If `row[0]` contains a placeholder like `$1`, an expression `RegExp` is
-  created and added to `expressions` to support dynamic matching in `tr()`.
+Runs `callback` in an asynchronous language context used by `lang()`, `tr()` and `trReverse()`. The context is preserved
+through promises without affecting concurrent callbacks.
 
-Typical CSV snippet:
-
-```csv
-hello;Hello
-"Hello, $1";"Hello, $1"
-"You have $1 new messages";"You have $1 new messages"
-```
+## Scope
 
-## Typical use cases
-
-Here are some scenarios where `@itrocks/translate` is a good fit:
-
-1. **Translating UI labels and messages in a Node.js application**
-   - Keep a simple `locales/<lang>.csv` file with two columns: source and
-     translation.
-   - At startup, call `trInit('<lang>')` and `trLoad('locales/<lang>.csv')`.
-   - Use `tr('settings')`, `tr('Save changes')`, etc., in your rendering
-     or logging code.
-
-2. **Integrating with a template or transformer system**
-   - Combine `@itrocks/translate` with higher‑level packages such as
-     `@itrocks/transformer` or `@itrocks/property-translate` to automatically
-     translate values when rendering views or model properties.
-
-3. **Dynamic messages with parameters**
-   - Define entries in your CSV containing `$1`, `$2`, ... placeholders.
-   - At runtime, call `tr('You have $1 new messages', ['3'])`.
-   - The placeholders are replaced by the elements of the `parts` array.
-
-4. **Expression‑based translations**
-   - Use keys with `$1` in your CSV (for example, `"Hello, $1"`).
-   - When you call `tr('Hello, John')`, `@itrocks/translate` matches the
-     pattern, translates `"John"` if possible, and then builds the final
-     sentence using the captured parts.
-
-5. **Inspecting and debugging translations**
-   - Use `translations.size` to quickly see how many entries were loaded.
-   - Inspect `translations.get('some key')` or iterate over the map when
-     debugging missing or incorrect translations.
+The package deliberately does not manage locale negotiation, plural rules or fallback chains. Applications and
+higher-level frameworks remain responsible for those policies.

package/cjs/catalog.d.ts

@@ -0,0 +1,5 @@
+export type Catalog = Map<string, string>;
+export declare const translations: Map<string, string>;
+export declare function catalog(language: string): Catalog;
+export declare function catalogClear(language: string): void;
+export declare function catalogLoad(file: string, language: string): Promise<void>;

package/cjs/catalog.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translations = void 0;
+exports.catalog = catalog;
+exports.catalogClear = catalogClear;
+exports.catalogLoad = catalogLoad;
+const promises_1 = require("node:fs/promises");
+const promises_2 = require("node:fs/promises");
+const parseCsv = require('papaparse').parse;
+const catalogs = new Map;
+exports.translations = new Map;
+catalogs.set('en-US', exports.translations);
+function catalog(language) {
+    let result = catalogs.get(language);
+    if (!result) {
+        result = new Map;
+        catalogs.set(language, result);
+    }
+    return result;
+}
+function catalogClear(language) {
+    catalogs.clear();
+    exports.translations.clear();
+    catalogs.set(language, exports.translations);
+}
+async function catalogLoad(file, language) {
+    try {
+        await (0, promises_1.access)(file);
+    }
+    catch {
+        return;
+    }
+    const translations = catalog(language);
+    return (0, promises_2.readFile)(file, 'utf-8')
+        .then((data) => parseCsv(data, { delimiter: ';' }).data)
+        .then(data => data.forEach(([source, target]) => {
+        if ((typeof source !== 'string') || (typeof target !== 'string') || (source === target))
+            return;
+        translations.set(source, target);
+    }));
+}
+//# sourceMappingURL=catalog.js.map

package/cjs/translate.d.ts

@@ -1,11 +1,12 @@
-export declare const DefaultOptions: Options;
-export declare const expressions: Set<RegExp>;
-export declare const translations: Map<string, string>;
-export declare function lang(): string;
 export type Options = {
     ucFirst?: boolean;
 };
+export declare const DefaultOptions: Options;
+export declare function lang(): string;
 export declare function tr(text: string, options: Options): string;
 export declare function tr(text: string, parts?: string[], options?: Options): string;
-export declare function trInit(lang: string): void;
-export declare function trLoad(file: string): Promise<void>;
+export declare function trInit(language: string): void;
+export declare function trLoad(file: string, language?: string): Promise<void>;
+export declare function trReverse(text: string): string;
+export declare function trWithLanguage<T>(language: string, callback: () => T): T;
+export { translations } from './catalog';

package/cjs/translate.js

@@ -1,21 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.translations = exports.expressions = exports.DefaultOptions = void 0;
+exports.translations = exports.DefaultOptions = void 0;
 exports.lang = lang;
 exports.tr = tr;
 exports.trInit = trInit;
 exports.trLoad = trLoad;
-const promises_1 = require("node:fs/promises");
-const promises_2 = require("node:fs/promises");
-const parseCsv = require('papaparse').parse;
+exports.trReverse = trReverse;
+exports.trWithLanguage = trWithLanguage;
+const node_async_hooks_1 = require("node:async_hooks");
+const catalog_1 = require("./catalog");
+const catalog_2 = require("./catalog");
+const catalog_3 = require("./catalog");
 exports.DefaultOptions = {
     ucFirst: true
 };
-exports.expressions = new Set;
-exports.translations = new Map;
-let language = 'en-US';
+const languageScope = new node_async_hooks_1.AsyncLocalStorage();
+let defaultLanguage = 'en-US';
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 function lang() {
-    return language;
+    return languageScope.getStore() ?? defaultLanguage;
 }
 function tr(text, parts, options) {
     if (!Array.isArray(parts)) {
@@ -27,10 +32,12 @@ function tr(text, parts, options) {
     let partsCount = parts.length;
     const firstChar = text[0];
     const ucFirst = (options?.ucFirst ?? exports.DefaultOptions.ucFirst) && (firstChar >= 'A') && (firstChar <= 'Z');
-    let translated = exports.translations.get(text)
-        ?? (ucFirst ? exports.translations.get(firstChar.toLocaleLowerCase() + text.slice(1)) : undefined)
-        ?? exports.translations.get(text.toLocaleLowerCase())
-        ?? trMatch(text, parts);
+    const active = (0, catalog_1.catalog)(lang());
+    let translated = active.get(text)
+        ?? (ucFirst ? active.get(firstChar.toLocaleLowerCase() + text.slice(1)) : undefined)
+        ?? active.get(text.toLocaleLowerCase())
+        ?? trMatch(text, parts, active)
+        ?? (ucFirst ? trMatch(firstChar.toLocaleLowerCase() + text.slice(1), parts, active) : undefined);
     if (!translated) {
         const separator = (text.length > 1)
             ? ['.', '?', '!', ';', ':', ',', '(', ')'].find(c => text.includes(c))
@@ -49,42 +56,55 @@ function tr(text, parts, options) {
     }
     return firstSpaces + translated + lastSpaces;
 }
-function trInit(lang) {
-    language = lang;
-    exports.expressions.clear();
-    exports.translations.clear();
+function trInit(language) {
+    defaultLanguage = language;
+    (0, catalog_2.catalogClear)(language);
 }
-async function trLoad(file) {
-    try {
-        await (0, promises_1.access)(file);
-    }
-    catch {
-        return;
-    }
-    return (0, promises_2.readFile)(file, 'utf-8')
-        .then((data) => parseCsv(data, { delimiter: ';' }).data)
-        .then(data => data.forEach(row => {
-        exports.translations.set(row[0], row[1]);
-        if (row[0].includes('$')) {
-            exports.expressions.add(RegExp('^' + row[0].replace(/(\$[0-9]+)/, '(.*)') + '$'));
-        }
-    }));
+function trLoad(file, language = defaultLanguage) {
+    return (0, catalog_3.catalogLoad)(file, language);
 }
-function trMatch(text, parts) {
-    for (const expression of exports.expressions) {
+function trMatch(text, parts, active) {
+    for (const [source, translated] of active) {
+        if (!source.includes('$'))
+            continue;
+        const indexes = [];
+        let last = 0;
+        let pattern = '^';
+        for (const match of source.matchAll(/\$([1-9][0-9]*)/g)) {
+            pattern += escapeRegExp(source.slice(last, match.index)) + '(.*?)';
+            indexes.push(Number(match[1]));
+            last = match.index + match[0].length;
+        }
+        pattern += escapeRegExp(source.slice(last)) + '$';
+        const expression = RegExp(pattern);
         const match = text.match(expression);
         if (!match)
             continue;
-        let counter = parts.length;
-        const replacements = [];
         const trParts = [...parts];
-        for (const part of match.slice(1)) {
+        for (const [offset, part] of match.slice(1).entries()) {
             const translatedPart = tr(part);
-            trParts.push(translatedPart[0].toLocaleLowerCase() + translatedPart.slice(1));
-            replacements.push('$' + trParts.length);
+            trParts[indexes[offset] ?? (offset + 1)] = (translatedPart && (translatedPart !== part))
+                ? translatedPart[0].toLocaleLowerCase() + translatedPart.slice(1)
+                : translatedPart;
+        }
+        let result = translated;
+        for (let index = trParts.length - 1; index > 0; index--) {
+            result = result.replaceAll('$' + index, trParts[index] ?? '');
         }
-        const trText = expression.source.slice(1, -1).replaceAll('(.*)', () => '$' + ++counter);
-        return tr(trText, trParts);
+        return result;
     }
 }
+function trReverse(text) {
+    for (const [source, translated] of (0, catalog_1.catalog)(lang())) {
+        if ((translated === text)
+            || (translated === text[0].toLocaleLowerCase() + text.slice(1)))
+            return source;
+    }
+    return text;
+}
+function trWithLanguage(language, callback) {
+    return languageScope.run(language, callback);
+}
+var catalog_4 = require("./catalog");
+Object.defineProperty(exports, "translations", { enumerable: true, get: function () { return catalog_4.translations; } });
 //# sourceMappingURL=translate.js.map

package/package.json

@@ -42,7 +42,8 @@
 		"url": "git+https://github.com/itrocks-ts/translate.git"
 	},
 	"scripts": {
-		"build": "tsc"
+		"build": "tsc",
+		"test": "npm run build && node --test test/*.test.js"
 	},
-	"version": "0.2.2"
+	"version": "0.2.4"
 }