@itrocks/translate 0.2.2 → 0.2.3

package/README.md

@@ -29,6 +29,7 @@ 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.
 
@@ -103,6 +104,24 @@ async function initTranslations() {
 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 trWithLanguage('fr-FR', async () => {
+  console.log(tr('Hello')) // Bonjour
+})
+```
+
+`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
@@ -240,7 +259,7 @@ active language and want to reload translation data.
 ### `trLoad()`
 
 ```ts
-async function trLoad(file: string): Promise<void | unknown>
+async function trLoad(file: string, options?: LoadOptions): Promise<void | unknown>
 ```
 
 Loads translations from a **semicolon‑separated CSV file** at the given path.
@@ -253,6 +272,9 @@ Behavior:
   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()`.
@@ -265,6 +287,16 @@ hello;Hello
 "You have $1 new messages";"You have $1 new messages"
 ```
 
+### `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:

package/cjs/translate.d.ts

@@ -1,11 +1,16 @@
+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 type Options = {
-    ucFirst?: boolean;
-};
 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, options?: LoadOptions): Promise<void>;
+export declare function trWithLanguage<T>(language: string, callback: () => T): T;

package/cjs/translate.js

@@ -5,6 +5,8 @@ exports.lang = lang;
 exports.tr = tr;
 exports.trInit = trInit;
 exports.trLoad = trLoad;
+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;
@@ -13,9 +15,21 @@ exports.DefaultOptions = {
 };
 exports.expressions = new Set;
 exports.translations = new Map;
-let language = 'en-US';
+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 lang() {
-    return language;
+    return languageScope.getStore() ?? defaultLanguage;
 }
 function tr(text, parts, options) {
     if (!Array.isArray(parts)) {
@@ -27,10 +41,11 @@ 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 = 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);
     if (!translated) {
         const separator = (text.length > 1)
             ? ['.', '?', '!', ';', ':', ',', '(', ')'].find(c => text.includes(c))
@@ -49,42 +64,74 @@ function tr(text, parts, options) {
     }
     return firstSpaces + translated + lastSpaces;
 }
-function trInit(lang) {
-    language = lang;
+function trInit(language) {
+    defaultLanguage = language;
+    catalogs.clear();
     exports.expressions.clear();
     exports.translations.clear();
+    catalogs.set(language, { expressions: exports.expressions, translations: exports.translations });
 }
-async function trLoad(file) {
+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 => {
-        exports.translations.set(row[0], row[1]);
-        if (row[0].includes('$')) {
-            exports.expressions.add(RegExp('^' + row[0].replace(/(\$[0-9]+)/, '(.*)') + '$'));
+        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 trMatch(text, parts) {
-    for (const expression of exports.expressions) {
+function trWithLanguage(language, callback) {
+    return languageScope.run(language, callback);
+}
+function trMatch(text, parts, active) {
+    for (const expression of active.expressions) {
         const match = text.match(expression);
         if (!match)
             continue;
-        let counter = parts.length;
-        const replacements = [];
+        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 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[data?.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 escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 //# 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.3"
 }