@itrocks/translate 0.2.3 → 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,313 +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()`,
-- isolate concurrent request languages with `trWithLanguage()`,
-- 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')
+Translation sources stay in English. Each semicolon-separated CSV file maps them to one language:
 
-  // 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"
-}
-
-main().catch(console.error)
+```csv
+hello;bonjour
+private: $1 recipients;privée : $1 destinataires
 ```
 
-### Complete example with composite patterns
-
-`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.
+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.
 
-You can also store patterns with placeholders in the translation file. When a
-pattern matches the source text, `tr()` automatically:
+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.
 
-- 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')
-
-  // 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')
-
-  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"
+import { tr, trInit, trLoad, trReverse, trWithLanguage } from '@itrocks/translate'
 
-  // 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)
-```
-
-### Concurrent request languages
-
-Load each catalog once, then run request work in its own asynchronous language context.
-The context is preserved through promises without changing other concurrent requests:
-
-```ts
 trInit('en-US')
-await trLoad('locales/fr-FR.csv', { language: 'fr-FR' })
+await trLoad('locales/fr-FR.csv', 'fr-FR')
 
 await trWithLanguage('fr-FR', async () => {
-  console.log(tr('Hello')) // Bonjour
+  console.log(tr('Hello'))                           // Bonjour
+  console.log(tr('Private: $1 recipients.', ['2'])) // Privée : 2 destinataires.
+  console.log(trReverse('Bonjour'))                  // Hello
 })
 ```
 
-`trLoad(file, { language, reverse: true })` loads the second CSV column as the
-source and the first as the target. This is useful while migrating templates that
-temporarily contain literals in both the source and target languages.
-
-> **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`
-
-```ts
-export const expressions: Set<RegExp>
-```
-
-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`.
-
-Each such key generates a regular expression that is later used by `tr()` to
-match dynamic sentences and extract sub‑parts for translation.
-
-### `translations`
-
-```ts
-export const translations: Map<string, 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.
-
-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`
-
-```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.
-
 ### `lang()`
 
 ```ts
 function lang(): string
 ```
 
-Returns the **current language code** previously set with `trInit()`.
-
-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.
+Returns the language of the current asynchronous context, or the default language set by `trInit()`.
 
 ### `tr()`
 
 ```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
 ```
 
-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:
+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.
+
+When `ucFirst` is enabled, an uppercase source initial also produces an uppercase translated initial:
 
 ```ts
-tr('hello')
-tr('Hello', { ucFirst: false })
-tr('welcome.$1', ['John'])
-tr('You have $1 new messages', ['3'])
+export type Options = {
+  ucFirst?: boolean
+}
+
+export const DefaultOptions: Options = {
+  ucFirst: true
+}
 ```
 
 ### `trInit()`
 
 ```ts
-function trInit(lang: string): void
+function trInit(language: string): void
 ```
 
-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`.
-
-Call this once per language at application startup, or whenever you change the
-active language and want to reload translation data.
+Sets the default language and clears all previously loaded catalogs. Call it once before loading catalogs.
 
 ### `trLoad()`
 
 ```ts
-async function trLoad(file: string, options?: LoadOptions): Promise<void | unknown>
+function trLoad(file: string, language?: string): Promise<void | unknown>
 ```
 
-Loads translations from a **semicolon‑separated CSV file** at the given path.
-
-Behavior:
+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.
 
-- 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.
-- `options.language` selects the catalog to populate; it defaults to the language
-  selected by `trInit()`.
-- `options.reverse` swaps the source and translated columns while loading.
-- 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()`.
+### `trReverse()`
 
-Typical CSV snippet:
-
-```csv
-hello;Hello
-"Hello, $1";"Hello, $1"
-"You have $1 new messages";"You have $1 new messages"
+```ts
+function trReverse(text: string): string
 ```
 
+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.
+
 ### `trWithLanguage()`
 
 ```ts
 function trWithLanguage<T>(language: string, callback: () => T): T
 ```
 
-Runs `callback` in an asynchronous language context. `lang()` and `tr()` use that
-language for the callback and all asynchronous work it starts. Concurrent contexts
-remain isolated.
-
-## 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.
+Runs `callback` in an asynchronous language context used by `lang()`, `tr()` and `trReverse()`. The context is preserved
+through promises without affecting concurrent callbacks.
+
+## Scope
+
+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,16 +1,12 @@
-export type LoadOptions = {
-    language?: string;
-    reverse?: boolean;
-};
 export type Options = {
     ucFirst?: boolean;
 };
 export declare const DefaultOptions: Options;
-export declare const expressions: Set<RegExp>;
-export declare const translations: Map<string, string>;
 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(language: string): void;
-export declare function trLoad(file: string, options?: LoadOptions): Promise<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,32 +1,23 @@
 "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;
+exports.trReverse = trReverse;
 exports.trWithLanguage = trWithLanguage;
 const node_async_hooks_1 = require("node:async_hooks");
-const promises_1 = require("node:fs/promises");
-const promises_2 = require("node:fs/promises");
-const parseCsv = require('papaparse').parse;
+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;
-const catalogs = new Map;
-const expressionData = new WeakMap;
 const languageScope = new node_async_hooks_1.AsyncLocalStorage();
 let defaultLanguage = 'en-US';
-catalogs.set(defaultLanguage, { expressions: exports.expressions, translations: exports.translations });
-function catalog(language = lang()) {
-    let value = catalogs.get(language);
-    if (!value) {
-        value = { expressions: new Set, translations: new Map };
-        catalogs.set(language, value);
-    }
-    return value;
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 function lang() {
     return languageScope.getStore() ?? defaultLanguage;
@@ -41,11 +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');
-    const active = catalog();
-    let translated = active.translations.get(text)
-        ?? (ucFirst ? active.translations.get(firstChar.toLocaleLowerCase() + text.slice(1)) : undefined)
-        ?? active.translations.get(text.toLocaleLowerCase())
-        ?? trMatch(text, parts, active);
+    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))
@@ -66,61 +58,32 @@ function tr(text, parts, options) {
 }
 function trInit(language) {
     defaultLanguage = language;
-    catalogs.clear();
-    exports.expressions.clear();
-    exports.translations.clear();
-    catalogs.set(language, { expressions: exports.expressions, translations: exports.translations });
+    (0, catalog_2.catalogClear)(language);
 }
-async function trLoad(file, options = {}) {
-    try {
-        await (0, promises_1.access)(file);
-    }
-    catch {
-        return;
-    }
-    const active = catalog(options.language ?? defaultLanguage);
-    return (0, promises_2.readFile)(file, 'utf-8')
-        .then((data) => parseCsv(data, { delimiter: ';' }).data)
-        .then(data => data.forEach(row => {
-        const [source, target] = options.reverse ? [row[1], row[0]] : row;
-        if ((typeof source !== 'string') || (typeof target !== 'string'))
-            return;
-        active.translations.set(source, target);
-        if (source.includes('$')) {
-            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);
-            expressionData.set(expression, { indexes, source });
-            active.expressions.add(expression);
-        }
-    }));
-}
-function trWithLanguage(language, callback) {
-    return languageScope.run(language, callback);
+function trLoad(file, language = defaultLanguage) {
+    return (0, catalog_3.catalogLoad)(file, language);
 }
 function trMatch(text, parts, active) {
-    for (const expression of active.expressions) {
+    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;
-        const data = expressionData.get(expression);
-        let counter = 0;
-        const source = data?.source
-            ?? expression.source.slice(1, -1).replace(/\(\.\*\??\)/g, () => '$' + ++counter);
-        const translated = active.translations.get(source);
-        if (!translated)
-            continue;
         const trParts = [...parts];
         for (const [offset, part] of match.slice(1).entries()) {
             const translatedPart = tr(part);
-            trParts[data?.indexes[offset] ?? (offset + 1)] = (translatedPart && (translatedPart !== part))
+            trParts[indexes[offset] ?? (offset + 1)] = (translatedPart && (translatedPart !== part))
                 ? translatedPart[0].toLocaleLowerCase() + translatedPart.slice(1)
                 : translatedPart;
         }
@@ -131,7 +94,17 @@ function trMatch(text, parts, active) {
         return result;
     }
 }
-function escapeRegExp(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+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

@@ -45,5 +45,5 @@
 		"build": "tsc",
 		"test": "npm run build && node --test test/*.test.js"
 	},
-	"version": "0.2.3"
+	"version": "0.2.4"
 }