intl-template 1.0.6 → 1.0.7

package/README.md

@@ -1,19 +1,8 @@
-# intel-template
+# intl-template
 
-A tiny i18n/l10n TTL(Tagged Template Literals) function
+A tiny i18n/l10n helper built on JavaScript Tagged Template Literals.
 
-## Table of Contents
-
-- [intel-template](#intel-template)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Usage](#usage)
-    - [Use browser specifies locale](#use-browser-specifies-locale)
-    - [Use with React](#use-with-react)
-    - [Specify slot order](#specify-slot-order)
-    - [Nested](#nested)
-    - [Function slot](#function-slot)
-    - [Call as function](#call-as-function)
+`intl-template` lets source strings stay close to your UI code while translations live in a simple locale-indexed template map.
 
 ## Installation
 
@@ -21,96 +10,187 @@ A tiny i18n/l10n TTL(Tagged Template Literals) function
 npm install intl-template
 ```
 
-## Usage
+## Quick Start
 
-```
-import translation from "intl-template"
+```javascript
+import translation, { l10n } from "intl-template"
 
+translation.locale = "es-ES"
 translation.templates["es-ES"] = {
-    "hello {}": "hola {}"
+    "hello {}": "hola {}",
 }
 
-const l10n = translation.translate.bind(null, "es-ES")
+const name = "Willow"
 
-const name = "willow";
-
-console.log(l10n`hello ${name}`)
-// => hola willow
+console.log(l10n`hello ${name}`.toString())
+// => hola Willow
 ```
 
-### Use browser specifies locale
+Every interpolation in a tagged template becomes `{}` in the translation key. For example, `l10n`hello ${name}`` looks up the key `"hello {}"`.
+
+By default, translations return a `Runes` array so React nodes and other non-string values can pass through unchanged. Call `.toString()` when you need plain text, or create a `Translation` instance in `"string"` mode.
+
+## Templates
+
+```javascript
+translation.templates["en-US"] = {
+    "hello {}": "hello {}",
+    "{} invited {}": "{} invited {}",
+}
+
+translation.templates["de-DE"] = {
+    "hello {}": "hallo {}",
+    "{} invited {}": "{1} wurde von {0} eingeladen",
+}
 ```
+
+Use `{}` to keep the original slot order. Use `{0}`, `{1}`, and later indexes when a locale needs a different order.
+
+## Locale
+
+The shared `translation` instance uses `navigator.language` when it is available, then falls back to `"en"`. You can also set the locale explicitly.
+
+```javascript
 import translation, { l10n } from "intl-template"
 
-translation.templates["es-ES"] = {
-    "hello {}": "hola {}"
+const browserLocale = navigator.language
+
+translation.locale = browserLocale
+translation.templates[browserLocale] = {
+    "hello {}": "hola {}",
 }
 
-// l10n = translation.translate.bind(null, navigator,language)
+console.log(l10n`hello ${"Willow"}`.toString())
+// => hola Willow
+```
 
-const name = "willow";
+## Examples
 
-console.log(l10n`hello ${name}`)
-// => hola willow
-```
+### React
 
-### Use with React
+The default `"react"` mode keeps interpolated values as values, so JSX can be used inside a translation.
 
-```javascript
+```jsx
+import translation, { l10n } from "intl-template"
 
-function SomeComponent({ name }) {
+translation.locale = "es-ES"
+translation.templates["es-ES"] = {
+    "hello {}": "hola {}",
+}
+
+function Greeting({ name }) {
     return (
-        <div>
-            {l10n`hello ${<b>{name}</b>}`}
-        </div>
+        <p>
+            {l10n`hello ${<strong key="name">{name}</strong>}`}
+        </p>
     )
 }
 ```
 
-### Specify slot order
+### Slot Order
 
-```
+```javascript
+translation.locale = "de-DE"
 translation.templates["de-DE"] = {
-    "hello {} and {}": "hallo {1} und {0}"
+    "{} invited {}": "{1} wurde von {0} eingeladen",
 }
 
-const l10n = translation.translate.bind(null, "de-DE")
+const inviter = "Willow"
+const guest = "Jack"
+
+console.log(l10n`${inviter} invited ${guest}`.toString())
+// => Jack wurde von Willow eingeladen
+```
+
+### Nested Translations
 
-const name1 = "willow"
-const name2 = "jack"
+```javascript
+translation.locale = "de-DE"
+translation.templates["de-DE"] = {
+    "Bill": "Schmidt",
+    "hello {}": "hallo {}",
+}
 
-console.log(l10n`hello ${name1} and ${name2}`)
-// => holla jack und willow
+console.log(l10n`hello ${l10n`Bill`}`.toString())
+// => hallo Schmidt
 ```
 
-### Nested
+### Function Slots
+
+When a slot is a function, it receives the active locale.
 
 ```javascript
+translation.locale = "de-DE"
 translation.templates["de-DE"] = {
-    "bill": "schmidt",
-    "hello {}": "hallo {1}"
+    "current locale: {}": "aktuelle Sprache: {}",
 }
 
-const l10n = translation.translate.bind(null, "de-DE")
+console.log(l10n`current locale: ${locale => locale}`.toString())
+// => aktuelle Sprache: de-DE
+```
+
+### Call as a Function
+
+Tagged templates and function calls use the same placeholder format.
 
-l10n`hello ${l10n`bill`}` // => hallo schmidt
+```javascript
+translation.locale = "es-ES"
+translation.templates["es-ES"] = {
+    "hello {}": "hola {}",
+}
+
+console.log(l10n("hello {}", "Willow").toString())
+// => hola Willow
 ```
 
-### Function slot
+### String Mode
 
 ```javascript
-translation.templates["de-DE"] = {
-    "bill": "schmidt",
-    "hello {}": "hallo {1}"
+import { Translation } from "intl-template"
+
+const translation = new Translation("es-ES", "string")
+
+translation.templates["es-ES"] = {
+    "hello {}": "hola {}",
 }
 
-const l10n = translation.translate.bind(null, "de-DE")
+const t = translation.translate
 
-l10n`hello ${(locale) => 123}` // => hallo 123
+console.log(t`hello ${"Willow"}`)
+// => hola Willow
 ```
 
-### Call as function
+## API
+
+### `translation`
+
+The default shared `Translation` instance.
+
+### `l10n`
+
+A shorthand for `translation.translate`.
+
+### `new Translation(defaultLocale, mode)`
+
+Creates an isolated translation instance.
+
+- `defaultLocale`: locale used by this instance.
+- `mode`: `"react"` by default, or `"string"` for plain string output.
+
+### `translation.locale`
+
+The active locale used by `translate`.
+
+### `translation.templates`
+
+Locale-indexed translation templates.
 
 ```javascript
-l10n("hello {}", name)
+translation.templates["es-ES"] = {
+    "source {}": "translated {}",
+}
 ```
+
+### `translation.translate(strings, ...parts)`
+
+Translates a tagged template or a string with `{}` placeholders.

package/intl.cjs

@@ -43,23 +43,43 @@ class Runes extends Array {
     return this.join("");
   }
 }
+var SLOT_RE = /\{(\d*)\}/g;
+var TEMPLATE_KEY_CACHE = new WeakMap;
 function parseTemplate(templateString) {
-  const order = [];
   const template = [];
-  const parts = templateString.split(/({\d*})/);
-  parts.forEach((part) => {
-    if (part.match(/^{\d*}$/)) {
-      if (part === "{}") {
-        order.push(order.length);
-      } else {
-        order.push(parseInt(part.slice(1, -1), 10));
-      }
-    } else {
-      template.push(part);
-    }
-  });
+  const order = [];
+  let lastIndex = 0;
+  let match;
+  SLOT_RE.lastIndex = 0;
+  while ((match = SLOT_RE.exec(templateString)) !== null) {
+    template.push(templateString.slice(lastIndex, match.index));
+    order.push(match[1] === "" ? order.length : +match[1]);
+    lastIndex = SLOT_RE.lastIndex;
+  }
+  template.push(templateString.slice(lastIndex));
   return { template, order };
 }
+function compileRegionTemplates(regionTemplates) {
+  const region = {};
+  for (const key in regionTemplates) {
+    region[key] = parseTemplate(regionTemplates[key]);
+  }
+  return region;
+}
+function getTemplateKey(strings) {
+  if (!strings.raw) {
+    return strings.join("{}");
+  }
+  let key = TEMPLATE_KEY_CACHE.get(strings);
+  if (key === undefined) {
+    key = strings.join("{}");
+    TEMPLATE_KEY_CACHE.set(strings, key);
+  }
+  return key;
+}
+function toTemplateString(value) {
+  return value == null ? "" : value;
+}
 
 class Translation {
   mode = "react";
@@ -68,23 +88,25 @@ class Translation {
     this.mode = mode;
     this.locale = defaultLocale || globalThis?.navigator?.language || "en";
   }
-  #templates = new Proxy({}, {
-    get(templates, locale) {
-      return new Proxy(templates[locale] || {}, {
-        set(region, key, value) {
-          if (typeof value !== "string") {
-            throw new Error("Template must be a string.");
-          }
-          region[key] = parseTemplate(value);
-          return true;
-        }
-      });
+  #regions = {};
+  #regionProxies = {};
+  #templates = new Proxy(this.#regions, {
+    get: (regions, locale) => {
+      const region = regions[locale];
+      if (!region) {
+        return new Proxy({}, REGION_HANDLER);
+      }
+      let proxy = this.#regionProxies[locale];
+      if (!proxy) {
+        proxy = new Proxy(region, REGION_HANDLER);
+        this.#regionProxies[locale] = proxy;
+      }
+      return proxy;
     },
-    set(templates, locale, regionTemplates) {
-      templates[locale] = Object.entries(regionTemplates).reduce((region, [key, value]) => {
-        region[key] = parseTemplate(value);
-        return region;
-      }, {});
+    set: (regions, locale, regionTemplates) => {
+      const region = compileRegionTemplates(regionTemplates);
+      regions[locale] = region;
+      this.#regionProxies[locale] = new Proxy(region, REGION_HANDLER);
       return true;
     }
   });
@@ -92,46 +114,59 @@ class Translation {
     return this.#templates;
   }
   set templates(value) {
-    Object.entries(value).forEach(([locale, regionTemplates]) => {
-      this.#templates[locale] = regionTemplates;
-    });
-    return true;
+    for (const locale in value) {
+      this.#templates[locale] = value[locale];
+    }
   }
   translate = (strings, ...parts) => {
     const locale = this.locale;
-    if (typeof strings === "string") {
-      strings = strings.split("{}");
-    }
-    const key = strings.join("{}");
-    const translation = this.#templates?.[locale];
-    let { template, order } = translation?.[key] || {};
-    if (!template) {
-      console.debug(`[intl-template]not match translate key, ${key}`, { translation, locale, strings, parts });
-      template = strings.slice();
-      order = parts.map((_, i) => i);
+    const isStringInput = typeof strings === "string";
+    const key = isStringInput ? strings : getTemplateKey(strings);
+    const compiled = this.#regions[locale]?.[key];
+    let template;
+    let order;
+    if (compiled) {
+      template = compiled.template;
+      order = compiled.order;
+    } else {
+      template = isStringInput ? strings.split("{}") : strings.slice();
     }
     if (parts.length !== template.length - 1) {
       throw new Error(`translate template parts length does not match. locale: ${locale}, key: ${key}`);
     }
-    const runes = template.reduce((runes2, template2, idx) => {
-      runes2.push(template2);
-      const orderIdx = order[idx];
-      if (orderIdx >= 0) {
-        const part = parts[orderIdx];
-        if (typeof part === "function") {
-          runes2.push(part(locale));
-        } else {
-          runes2.push(part);
+    const len = template.length;
+    if (this.mode !== "react") {
+      let result = "";
+      for (let idx = 0;idx < len; idx++) {
+        result += template[idx];
+        if (idx < parts.length) {
+          const part = parts[order ? order[idx] : idx];
+          result += toTemplateString(typeof part === "function" ? part(locale) : part);
         }
       }
-      return runes2;
-    }, new Runes);
-    if (this.mode !== "react") {
-      return runes.toString();
+      return result;
+    }
+    const runes = new Runes(len + parts.length);
+    let runeIdx = 0;
+    for (let idx = 0;idx < len; idx++) {
+      runes[runeIdx++] = template[idx];
+      if (idx < parts.length) {
+        const part = parts[order ? order[idx] : idx];
+        runes[runeIdx++] = typeof part === "function" ? part(locale) : part;
+      }
     }
     return runes;
   };
 }
+var REGION_HANDLER = {
+  set(region, key, value) {
+    if (typeof value !== "string") {
+      throw new Error("Template must be a string.");
+    }
+    region[key] = parseTemplate(value);
+    return true;
+  }
+};
 var translation = new Translation;
 var intl_default = translation;
 var l10n = translation.translate;

package/intl.d.ts

@@ -28,19 +28,19 @@ export class Translation {
      * @type {string}
      **/
     locale: string;
-    set templates(value: Proxy);
-    get templates(): Proxy;
+    set templates(value: any);
+    get templates(): any;
     /**
      * Translates a string based on the provided locale and strings.
      *
      * @param {TemplateStringsArray | string} strings - The string or array of strings to be translated.
      * @param {...any} parts - The dynamic parts to be inserted into the translated string.
-     * @returns {Runes} - The translated string with dynamic parts inserted.
+     * @returns {Runes | string} - The translated string with dynamic parts inserted.
      * @throws {Error} - If the length of the template parts does not match the length of the template.
      */
-    translate: (strings: TemplateStringsArray | string, ...parts: any[]) => Runes;
+    translate: (strings: TemplateStringsArray | string, ...parts: any[]) => Runes | string;
     #private;
 }
 export const translation: Translation;
 export default translation;
-export function l10n(strings: TemplateStringsArray | string, ...parts: any[]): Runes;
+export function l10n(strings: TemplateStringsArray | string, ...parts: any[]): Runes | string;

package/intl.js

@@ -4,31 +4,59 @@ export class Runes extends Array {
 	}
 }
 
+const SLOT_RE = /\{(\d*)\}/g
+const TEMPLATE_KEY_CACHE = new WeakMap()
+
 /**
  * Parses a template string and extracts the template parts and order of slots.
  * @param {string} templateString - The template string to parse.
  * @returns {{ template: string[], order: number[] }}
  */
 export function parseTemplate(templateString) {
-	const order = [];
-	const template = [];
-	const parts = templateString.split(/({\d*})/)
-	parts.forEach((part) => {
-		if (part.match(/^{\d*}$/)) {
-			if (part === '{}') {
-				order.push(order.length)
-			} else {
-				// slot with order, e.g. `{2}abc{1}def{0}`
-				order.push(parseInt(part.slice(1, -1), 10))
-			}
-		} else {
-			template.push(part)
-		}
-	})
+	const template = []
+	const order = []
+	let lastIndex = 0
+	let match
+
+	SLOT_RE.lastIndex = 0
+	while ((match = SLOT_RE.exec(templateString)) !== null) {
+		template.push(templateString.slice(lastIndex, match.index))
+		// `{}` keeps original auto-numbering: index = current order length
+		order.push(match[1] === "" ? order.length : +match[1])
+		lastIndex = SLOT_RE.lastIndex
+	}
+	template.push(templateString.slice(lastIndex))
 
 	return { template, order }
 }
 
+function compileRegionTemplates(regionTemplates) {
+	const region = {}
+	for (const key in regionTemplates) {
+		region[key] = parseTemplate(regionTemplates[key])
+	}
+
+	return region
+}
+
+function getTemplateKey(strings) {
+	if (!strings.raw) {
+		return strings.join("{}")
+	}
+
+	let key = TEMPLATE_KEY_CACHE.get(strings)
+	if (key === undefined) {
+		key = strings.join("{}")
+		TEMPLATE_KEY_CACHE.set(strings, key)
+	}
+
+	return key
+}
+
+function toTemplateString(value) {
+	return value == null ? "" : value
+}
+
 /**
  * Represents a Translation object that handles string translation based on locale and templates.
  */
@@ -55,26 +83,29 @@ export class Translation {
 	 * Templates object that stores the translation templates for each locale.
 	 * @type {Proxy}
 	 */
-	#templates = new Proxy({}, {
-		get(templates, locale) {
-			return new Proxy(templates[locale] || {}, {
-				set(region, key, value) {
-					if (typeof value !== "string") {
-						throw new Error("Template must be a string.")
-					}
+	#regions = {}
 
-					region[key] = parseTemplate(value)
+	#regionProxies = {}
 
-					return true
-				}
-			})
-		},
-		set(templates, locale, regionTemplates) {
-			templates[locale] = Object.entries(regionTemplates).reduce((region, [key, value]) => {
-				region[key] = parseTemplate(value)
+	#templates = new Proxy(this.#regions, {
+		get: (regions, locale) => {
+			const region = regions[locale]
+			if (!region) {
+				return new Proxy({}, REGION_HANDLER)
+			}
 
-				return region
-			}, {})
+			let proxy = this.#regionProxies[locale]
+			if (!proxy) {
+				proxy = new Proxy(region, REGION_HANDLER)
+				this.#regionProxies[locale] = proxy
+			}
+
+			return proxy
+		},
+		set: (regions, locale, regionTemplates) => {
+			const region = compileRegionTemplates(regionTemplates)
+			regions[locale] = region
+			this.#regionProxies[locale] = new Proxy(region, REGION_HANDLER)
 
 			return true
 		}
@@ -85,11 +116,9 @@ export class Translation {
 	}
 
 	set templates(value) {
-		Object.entries(value).forEach(([locale, regionTemplates]) => {
-			this.#templates[locale] = regionTemplates
-		})
-
-		return true
+		for (const locale in value) {
+			this.#templates[locale] = value[locale]
+		}
 	}
 
 	/**
@@ -97,53 +126,66 @@ export class Translation {
 	 *
 	 * @param {TemplateStringsArray | string} strings - The string or array of strings to be translated.
 	 * @param {...any} parts - The dynamic parts to be inserted into the translated string.
-	 * @returns {Runes} - The translated string with dynamic parts inserted.
+	 * @returns {Runes | string} - The translated string with dynamic parts inserted.
 	 * @throws {Error} - If the length of the template parts does not match the length of the template.
 	 */
 	translate = (strings, ...parts) => {
 		const locale = this.locale
-
-		if (typeof strings === "string") {
-			strings = strings.split("{}")
-		}
-
-		const key = strings.join("{}")
-		const translation = this.#templates?.[locale]
-		let { template, order } = translation?.[key] || {}
-		if (!template) {
-			console.debug(`[intl-template]not match translate key, ${key}`, { translation, locale, strings, parts })
-			template = strings.slice()
-			order = parts.map((_, i) => i)
+		const isStringInput = typeof strings === "string"
+		const key = isStringInput ? strings : getTemplateKey(strings)
+
+		const compiled = this.#regions[locale]?.[key]
+		let template
+		let order
+		if (compiled) {
+			template = compiled.template
+			order = compiled.order
+		} else {
+			template = isStringInput ? strings.split("{}") : strings.slice()
 		}
 
 		if (parts.length !== template.length - 1) {
 			throw new Error(`translate template parts length does not match. locale: ${locale}, key: ${key}`)
 		}
 
-		const runes = template.reduce((runes, template, idx) => {
-			runes.push(template)
-
-			const orderIdx = order[idx]
-			if (orderIdx >= 0) {
-				const part = parts[orderIdx]
-				if (typeof part === "function") {
-					runes.push(part(locale))
-				} else {
-					runes.push(part)
+		const len = template.length
+		if (this.mode !== "react") {
+			let result = ""
+			for (let idx = 0; idx < len; idx++) {
+				result += template[idx]
+				if (idx < parts.length) {
+					const part = parts[order ? order[idx] : idx]
+					result += toTemplateString(typeof part === "function" ? part(locale) : part)
 				}
 			}
 
-			return runes
-		}, new Runes())
+			return result
+		}
 
-		if (this.mode !== "react") {
-			return runes.toString()
+		const runes = new Runes(len + parts.length)
+		let runeIdx = 0
+		for (let idx = 0; idx < len; idx++) {
+			runes[runeIdx++] = template[idx]
+			if (idx < parts.length) {
+				const part = parts[order ? order[idx] : idx]
+				runes[runeIdx++] = typeof part === "function" ? part(locale) : part
+			}
 		}
 
 		return runes
 	}
 }
 
+const REGION_HANDLER = {
+	set(region, key, value) {
+		if (typeof value !== "string") {
+			throw new Error("Template must be a string.")
+		}
+		region[key] = parseTemplate(value)
+		return true
+	}
+}
+
 export const translation = new Translation()
 
 export default translation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intl-template",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "l10n tagged template literals",
   "type": "module",
   "main": "./intl.cjs",
@@ -15,7 +15,8 @@
   ],
   "scripts": {
     "build": "bun build --outfile intl.cjs --format cjs intl.js",
-    "postbuild": "rm *.d.ts && tsc --emitDeclarationOnly --allowJs -d --outDir . *.js"
+    "perf": "node --test intl.perf.test.js",
+    "postbuild": "rm *.d.ts && tsc --emitDeclarationOnly --allowJs -d --outDir . intl.js intl.test.js"
   },
   "keywords": [
     "i18n",