intor-translator 1.2.3 → 1.2.5

package/README.md

@@ -64,6 +64,8 @@ translator.t("hello"); // -> Hello World
 translator.t("greeting", { name: "John doe" }); // -> Hello, John doe!
 ```
 
+---
+
 ## Handlers & Hooks
 
 Intor Translator is powered by **a flexible pipeline** that lets you control how translations behave and how they are rendered.
@@ -94,5 +96,16 @@ Hooks run through the pipeline and can intercept any stage, use them to:
 
 ---
 
+# Rich Message Processing
+
+This module provides a semantic message processing flow for **_translated rich-formatted strings_**.
+
+- Tokenize → AST → renderer-driven output
+- Environment-agnostic by design
+
+Read the documentation: [Message Processing ↗](https://github.com/yiming-liao/intor-translator/tree/main/src/message)
+
+---
+
 **_For more advanced usage, see the full examples._**
 [View examples ↗](https://github.com/yiming-liao/intor-translator/tree/main/examples)

package/dist/index.cjs

@@ -4,7 +4,7 @@ var rura = require('rura');
 
 // src/translators/core-translator/core-translator.ts
 
-// src/translators/shared/utils/find-message-in-locales.ts
+// src/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
   messages,
   candidateLocales,
@@ -43,13 +43,13 @@ var findMessage = rura.rura.createHook(
 // src/pipeline/utils/make-handler-context.ts
 function makeHandlerContext(ctx) {
   return Object.freeze({
+    config: ctx.config,
+    messages: ctx.messages,
     locale: ctx.locale,
+    isLoading: ctx.isLoading,
     key: ctx.key,
     replacements: ctx.replacements,
-    messages: ctx.messages,
     candidateLocales: ctx.candidateLocales,
-    config: ctx.config,
-    isLoading: ctx.isLoading,
     rawMessage: ctx.rawMessage,
     formattedMessage: ctx.formattedMessage,
     meta: ctx.meta
@@ -70,7 +70,7 @@ var format = rura.rura.createHook(
   500
 );
 
-// src/translators/shared/utils/replace-values.ts
+// src/pipeline/hooks/interpolate/replace-values.ts
 var replaceValues = (message, params) => {
   if (!params || typeof params !== "object" || Object.keys(params).length === 0) {
     return message;
@@ -89,7 +89,7 @@ var replaceValues = (message, params) => {
   return replaced;
 };
 
-// src/pipeline/hooks/interpolate.ts
+// src/pipeline/hooks/interpolate/interpolate.ts
 var interpolate = rura.rura.createHook(
   "interpolate",
   (ctx) => {
@@ -143,7 +143,7 @@ var missing = rura.rura.createHook(
   400
 );
 
-// src/translators/shared/utils/resolve-candidate-locales.ts
+// src/shared/utils/resolve-candidate-locales.ts
 var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
   const fallbacks = fallbackLocalesMap?.[locale] || [];
   const filteredFallbacks = fallbacks.filter((l) => l !== locale);
@@ -220,7 +220,7 @@ var BaseTranslator = class {
   }
 };
 
-// src/translators/shared/has-key.ts
+// src/translators/methods/has-key.ts
 var hasKey = ({
   messages,
   locale,
@@ -228,11 +228,7 @@ var hasKey = ({
   targetLocale
 }) => {
   const candidateLocales = resolveCandidateLocales(targetLocale || locale);
-  const message = findMessageInLocales({
-    messages,
-    candidateLocales,
-    key
-  });
+  const message = findMessageInLocales({ messages, candidateLocales, key });
   return !!message;
 };
 function translate(options) {
@@ -344,4 +340,131 @@ var ScopeTranslator = class extends CoreTranslator {
   }
 };
 
+// src/message/tokenize/utils/extract-attributes.ts
+var ATTR_REGEX = /\s+([a-zA-Z_][a-zA-Z0-9_]*)="([^"]*)"/g;
+var extractAttributes = (input) => {
+  const attributes = {};
+  let match;
+  let consumed = "";
+  while (match = ATTR_REGEX.exec(input)) {
+    const [, key, value] = match;
+    attributes[key] = value;
+    consumed += match[0];
+  }
+  if (consumed.length !== input.length) {
+    return null;
+  }
+  return attributes;
+};
+
+// src/message/tokenize/tokenize.ts
+var OPEN_TAG_REGEX = /^<([a-zA-Z0-9_]+)([^>]*)>/;
+var CLOSE_TAG_REGEX = /^<\/([a-zA-Z0-9_]+)>/;
+var tokenize = (message) => {
+  const tokens = [];
+  let pos = 0;
+  let buffer = "";
+  const flushText = () => {
+    if (!buffer) return;
+    tokens.push({
+      type: "text",
+      value: buffer,
+      position: pos - buffer.length
+    });
+    buffer = "";
+  };
+  while (pos < message.length) {
+    const char = message[pos];
+    if (char === "<") {
+      const openMatch = message.slice(pos).match(OPEN_TAG_REGEX);
+      if (openMatch) {
+        const [, name, rawAttributes] = openMatch;
+        const attributes = extractAttributes(rawAttributes);
+        if (attributes) {
+          flushText();
+          tokens.push({
+            type: "tag-open",
+            name,
+            attributes,
+            position: pos
+          });
+          pos += openMatch[0].length;
+          continue;
+        }
+      }
+      const closeMatch = message.slice(pos).match(CLOSE_TAG_REGEX);
+      if (closeMatch) {
+        flushText();
+        tokens.push({
+          type: "tag-close",
+          name: closeMatch[1],
+          position: pos
+        });
+        pos += closeMatch[0].length;
+        continue;
+      }
+    }
+    buffer += char;
+    pos += 1;
+  }
+  flushText();
+  return tokens;
+};
+
+// src/message/ast/build-ast.ts
+function buildAST(tokens) {
+  const root = [];
+  const stack = [];
+  const pushNode = (node) => {
+    const parent = stack.at(-1);
+    if (parent) {
+      parent.children.push(node);
+    } else {
+      root.push(node);
+    }
+  };
+  for (const token of tokens) {
+    switch (token.type) {
+      case "text": {
+        pushNode({
+          type: "text",
+          value: token.value
+        });
+        break;
+      }
+      case "tag-open": {
+        const node = {
+          type: "tag",
+          name: token.name,
+          attributes: token.attributes,
+          children: []
+        };
+        pushNode(node);
+        stack.push(node);
+        break;
+      }
+      case "tag-close": {
+        const last = stack.pop();
+        if (!last || last.name !== token.name) {
+          throw new Error(
+            `Unmatched closing tag </${token.name}> at position ${token.position}`
+          );
+        }
+        break;
+      }
+    }
+  }
+  if (stack.length > 0) {
+    throw new Error(`Unclosed tag detected: <${stack.at(-1)?.name}>`);
+  }
+  return root;
+}
+
+// src/message/parse-rich-message.ts
+function parseRichMessage(message) {
+  const tokens = tokenize(message);
+  return buildAST(tokens);
+}
+
 exports.Translator = ScopeTranslator;
+exports.parseRichMessage = parseRichMessage;

package/dist/index.d.cts

@@ -430,4 +430,39 @@ declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, L ex
     scoped<PK extends LocalizedNodeKeys<M, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, ScopedLeafKeys<M, PK, L>> : ScopeTranslatorMethods<M, L>;
 }
 
-export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin };
+/** Semantic tag attributes map. */
+type Attributes = Record<string, string>;
+
+/** Semantic node produced by the AST builder. */
+type ASTNode = TextNode | TagNode;
+/** Plain text node in the semantic AST. */
+interface TextNode {
+    type: "text";
+    value: string;
+}
+/** Semantic tag node with attributes and nested children. */
+interface TagNode {
+    type: "tag";
+    name: string;
+    attributes: Attributes;
+    children: ASTNode[];
+}
+
+/**
+ * Parse a rich-formatted message string into a semantic AST.
+ *
+ * This function is a high-level entry point for processing translated
+ * messages that contain semantic tags (e.g. <b>, <a>, <i>).
+ *
+ * Internally, it performs the following steps:
+ *
+ * - message (string) ⬇
+ *   - tokenize
+ *   - build AST
+ *
+ * The returned AST represents the semantic structure of the message
+ * and is intended to be consumed by renderers or further processing stages.
+ */
+declare function parseRichMessage(message: string): ASTNode[];
+
+export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin, parseRichMessage };

package/dist/index.d.ts

@@ -430,4 +430,39 @@ declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, L ex
     scoped<PK extends LocalizedNodeKeys<M, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, ScopedLeafKeys<M, PK, L>> : ScopeTranslatorMethods<M, L>;
 }
 
-export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin };
+/** Semantic tag attributes map. */
+type Attributes = Record<string, string>;
+
+/** Semantic node produced by the AST builder. */
+type ASTNode = TextNode | TagNode;
+/** Plain text node in the semantic AST. */
+interface TextNode {
+    type: "text";
+    value: string;
+}
+/** Semantic tag node with attributes and nested children. */
+interface TagNode {
+    type: "tag";
+    name: string;
+    attributes: Attributes;
+    children: ASTNode[];
+}
+
+/**
+ * Parse a rich-formatted message string into a semantic AST.
+ *
+ * This function is a high-level entry point for processing translated
+ * messages that contain semantic tags (e.g. <b>, <a>, <i>).
+ *
+ * Internally, it performs the following steps:
+ *
+ * - message (string) ⬇
+ *   - tokenize
+ *   - build AST
+ *
+ * The returned AST represents the semantic structure of the message
+ * and is intended to be consumed by renderers or further processing stages.
+ */
+declare function parseRichMessage(message: string): ASTNode[];
+
+export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin, parseRichMessage };

package/dist/index.js

@@ -2,7 +2,7 @@ import { rura } from 'rura';
 
 // src/translators/core-translator/core-translator.ts
 
-// src/translators/shared/utils/find-message-in-locales.ts
+// src/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
   messages,
   candidateLocales,
@@ -41,13 +41,13 @@ var findMessage = rura.createHook(
 // src/pipeline/utils/make-handler-context.ts
 function makeHandlerContext(ctx) {
   return Object.freeze({
+    config: ctx.config,
+    messages: ctx.messages,
     locale: ctx.locale,
+    isLoading: ctx.isLoading,
     key: ctx.key,
     replacements: ctx.replacements,
-    messages: ctx.messages,
     candidateLocales: ctx.candidateLocales,
-    config: ctx.config,
-    isLoading: ctx.isLoading,
     rawMessage: ctx.rawMessage,
     formattedMessage: ctx.formattedMessage,
     meta: ctx.meta
@@ -68,7 +68,7 @@ var format = rura.createHook(
   500
 );
 
-// src/translators/shared/utils/replace-values.ts
+// src/pipeline/hooks/interpolate/replace-values.ts
 var replaceValues = (message, params) => {
   if (!params || typeof params !== "object" || Object.keys(params).length === 0) {
     return message;
@@ -87,7 +87,7 @@ var replaceValues = (message, params) => {
   return replaced;
 };
 
-// src/pipeline/hooks/interpolate.ts
+// src/pipeline/hooks/interpolate/interpolate.ts
 var interpolate = rura.createHook(
   "interpolate",
   (ctx) => {
@@ -141,7 +141,7 @@ var missing = rura.createHook(
   400
 );
 
-// src/translators/shared/utils/resolve-candidate-locales.ts
+// src/shared/utils/resolve-candidate-locales.ts
 var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
   const fallbacks = fallbackLocalesMap?.[locale] || [];
   const filteredFallbacks = fallbacks.filter((l) => l !== locale);
@@ -218,7 +218,7 @@ var BaseTranslator = class {
   }
 };
 
-// src/translators/shared/has-key.ts
+// src/translators/methods/has-key.ts
 var hasKey = ({
   messages,
   locale,
@@ -226,11 +226,7 @@ var hasKey = ({
   targetLocale
 }) => {
   const candidateLocales = resolveCandidateLocales(targetLocale || locale);
-  const message = findMessageInLocales({
-    messages,
-    candidateLocales,
-    key
-  });
+  const message = findMessageInLocales({ messages, candidateLocales, key });
   return !!message;
 };
 function translate(options) {
@@ -342,4 +338,130 @@ var ScopeTranslator = class extends CoreTranslator {
   }
 };
 
-export { ScopeTranslator as Translator };
+// src/message/tokenize/utils/extract-attributes.ts
+var ATTR_REGEX = /\s+([a-zA-Z_][a-zA-Z0-9_]*)="([^"]*)"/g;
+var extractAttributes = (input) => {
+  const attributes = {};
+  let match;
+  let consumed = "";
+  while (match = ATTR_REGEX.exec(input)) {
+    const [, key, value] = match;
+    attributes[key] = value;
+    consumed += match[0];
+  }
+  if (consumed.length !== input.length) {
+    return null;
+  }
+  return attributes;
+};
+
+// src/message/tokenize/tokenize.ts
+var OPEN_TAG_REGEX = /^<([a-zA-Z0-9_]+)([^>]*)>/;
+var CLOSE_TAG_REGEX = /^<\/([a-zA-Z0-9_]+)>/;
+var tokenize = (message) => {
+  const tokens = [];
+  let pos = 0;
+  let buffer = "";
+  const flushText = () => {
+    if (!buffer) return;
+    tokens.push({
+      type: "text",
+      value: buffer,
+      position: pos - buffer.length
+    });
+    buffer = "";
+  };
+  while (pos < message.length) {
+    const char = message[pos];
+    if (char === "<") {
+      const openMatch = message.slice(pos).match(OPEN_TAG_REGEX);
+      if (openMatch) {
+        const [, name, rawAttributes] = openMatch;
+        const attributes = extractAttributes(rawAttributes);
+        if (attributes) {
+          flushText();
+          tokens.push({
+            type: "tag-open",
+            name,
+            attributes,
+            position: pos
+          });
+          pos += openMatch[0].length;
+          continue;
+        }
+      }
+      const closeMatch = message.slice(pos).match(CLOSE_TAG_REGEX);
+      if (closeMatch) {
+        flushText();
+        tokens.push({
+          type: "tag-close",
+          name: closeMatch[1],
+          position: pos
+        });
+        pos += closeMatch[0].length;
+        continue;
+      }
+    }
+    buffer += char;
+    pos += 1;
+  }
+  flushText();
+  return tokens;
+};
+
+// src/message/ast/build-ast.ts
+function buildAST(tokens) {
+  const root = [];
+  const stack = [];
+  const pushNode = (node) => {
+    const parent = stack.at(-1);
+    if (parent) {
+      parent.children.push(node);
+    } else {
+      root.push(node);
+    }
+  };
+  for (const token of tokens) {
+    switch (token.type) {
+      case "text": {
+        pushNode({
+          type: "text",
+          value: token.value
+        });
+        break;
+      }
+      case "tag-open": {
+        const node = {
+          type: "tag",
+          name: token.name,
+          attributes: token.attributes,
+          children: []
+        };
+        pushNode(node);
+        stack.push(node);
+        break;
+      }
+      case "tag-close": {
+        const last = stack.pop();
+        if (!last || last.name !== token.name) {
+          throw new Error(
+            `Unmatched closing tag </${token.name}> at position ${token.position}`
+          );
+        }
+        break;
+      }
+    }
+  }
+  if (stack.length > 0) {
+    throw new Error(`Unclosed tag detected: <${stack.at(-1)?.name}>`);
+  }
+  return root;
+}
+
+// src/message/parse-rich-message.ts
+function parseRichMessage(message) {
+  const tokens = tokenize(message);
+  return buildAST(tokens);
+}
+
+export { ScopeTranslator as Translator, parseRichMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-translator",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "🤖 A modern, type-safe i18n engine.",
   "author": {
     "name": "Yiming Liao",
@@ -57,7 +57,8 @@
     "lint": "eslint",
     "lint:debug": "eslint --debug",
     "knip": "knip --config .config/knip.config.ts",
-    "examples:html": "vite --config examples/html/vite.config.ts"
+    "examples:html": "vite --config examples/html/basic/vite.config.ts",
+    "examples:html:rich": "vite --config examples/html/rich/vite.config.ts"
   },
   "dependencies": {
     "rura": "1.0.7"