intor-translator 1.2.4 → 1.2.6

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

@@ -340,9 +340,9 @@ var ScopeTranslator = class extends CoreTranslator {
   }
 };
 
-// src/message/tokenize/parse-attributes.ts
+// src/message/tokenize/utils/extract-attributes.ts
 var ATTR_REGEX = /\s+([a-zA-Z_][a-zA-Z0-9_]*)="([^"]*)"/g;
-var parseAttributes = (input) => {
+var extractAttributes = (input) => {
   const attributes = {};
   let match;
   let consumed = "";
@@ -379,7 +379,7 @@ var tokenize = (message) => {
       const openMatch = message.slice(pos).match(OPEN_TAG_REGEX);
       if (openMatch) {
         const [, name, rawAttributes] = openMatch;
-        const attributes = parseAttributes(rawAttributes);
+        const attributes = extractAttributes(rawAttributes);
         if (attributes) {
           flushText();
           tokens.push({
@@ -411,7 +411,7 @@ var tokenize = (message) => {
   return tokens;
 };
 
-// src/message/build-ast/build-ast.ts
+// src/message/ast/build-ast.ts
 function buildAST(tokens) {
   const root = [];
   const stack = [];
@@ -466,5 +466,23 @@ function parseRichMessage(message) {
   return buildAST(tokens);
 }
 
+// src/message/render/render.ts
+function render(nodes, renderer) {
+  return nodes.map((node) => {
+    if (node.type === "text") {
+      return renderer.text(node.value);
+    }
+    const children = render(node.children, renderer);
+    return renderer.tag(node.name, node.attributes, children);
+  });
+}
+
+// src/message/render-rich-message.ts
+function renderRichMessage(message, renderer) {
+  const nodes = parseRichMessage(message);
+  return render(nodes, renderer);
+}
+
 exports.Translator = ScopeTranslator;
 exports.parseRichMessage = parseRichMessage;
+exports.renderRichMessage = renderRichMessage;

package/dist/index.d.cts

@@ -430,7 +430,7 @@ 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>;
 }
 
-/** Parsed tag attributes map. */
+/** Semantic tag attributes map. */
 type Attributes = Record<string, string>;
 
 /** Semantic node produced by the AST builder. */
@@ -451,16 +451,49 @@ interface TagNode {
 /**
  * Parse a rich-formatted message string into a semantic AST.
  *
- * This is the high-level entry point for processing translated messages
- * that contain semantic tags (e.g. <b>, <a>, <i>).
+ * This function is a high-level entry point for processing translated
+ * messages that contain semantic tags (e.g. <b>, <a>, <i>).
  *
- * Internally, this function:
- * - Tokenizes the input string into semantic tokens
- * - Builds a nested AST from the token stream
+ * Internally, it performs the following steps:
  *
- * Consumers should treat the returned AST as a semantic structure
- * suitable for rendering or further processing.
+ * - 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 };
+/**
+ * Renderer interface for semantic message ASTs.
+ *
+ * A renderer defines how semantic nodes are transformed into a concrete output
+ * representation (e.g. string, DOM nodes, React elements).
+ *
+ * This interface is stateless by design.
+ * All rendering behavior is expressed through implementation.
+ */
+interface Renderer<Output> {
+    /** Render a plain text node. */
+    text(value: string): Output;
+    /** Render a semantic tag node with attributes and rendered children. */
+    tag(name: string, attributes: Attributes, children: Output[]): Output;
+}
+
+/**
+ * Render a rich-formatted message into a concrete output using a renderer.
+ *
+ * This function orchestrates the full rich message pipeline:
+ *
+ * - message (string) ⬇
+ *   - tokenize
+ *   - build AST
+ *   - render via provided renderer
+ *
+ * All rendering behavior is defined by the given renderer, making this
+ * function environment-agnostic (string, DOM, React, etc.).
+ */
+declare function renderRichMessage<Output>(message: string, renderer: Renderer<Output>): Output[];
+
+export { type ASTNode, 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 Renderer, 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, renderRichMessage };

package/dist/index.d.ts

@@ -430,7 +430,7 @@ 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>;
 }
 
-/** Parsed tag attributes map. */
+/** Semantic tag attributes map. */
 type Attributes = Record<string, string>;
 
 /** Semantic node produced by the AST builder. */
@@ -451,16 +451,49 @@ interface TagNode {
 /**
  * Parse a rich-formatted message string into a semantic AST.
  *
- * This is the high-level entry point for processing translated messages
- * that contain semantic tags (e.g. <b>, <a>, <i>).
+ * This function is a high-level entry point for processing translated
+ * messages that contain semantic tags (e.g. <b>, <a>, <i>).
  *
- * Internally, this function:
- * - Tokenizes the input string into semantic tokens
- * - Builds a nested AST from the token stream
+ * Internally, it performs the following steps:
  *
- * Consumers should treat the returned AST as a semantic structure
- * suitable for rendering or further processing.
+ * - 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 };
+/**
+ * Renderer interface for semantic message ASTs.
+ *
+ * A renderer defines how semantic nodes are transformed into a concrete output
+ * representation (e.g. string, DOM nodes, React elements).
+ *
+ * This interface is stateless by design.
+ * All rendering behavior is expressed through implementation.
+ */
+interface Renderer<Output> {
+    /** Render a plain text node. */
+    text(value: string): Output;
+    /** Render a semantic tag node with attributes and rendered children. */
+    tag(name: string, attributes: Attributes, children: Output[]): Output;
+}
+
+/**
+ * Render a rich-formatted message into a concrete output using a renderer.
+ *
+ * This function orchestrates the full rich message pipeline:
+ *
+ * - message (string) ⬇
+ *   - tokenize
+ *   - build AST
+ *   - render via provided renderer
+ *
+ * All rendering behavior is defined by the given renderer, making this
+ * function environment-agnostic (string, DOM, React, etc.).
+ */
+declare function renderRichMessage<Output>(message: string, renderer: Renderer<Output>): Output[];
+
+export { type ASTNode, 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 Renderer, 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, renderRichMessage };

package/dist/index.js

@@ -338,9 +338,9 @@ var ScopeTranslator = class extends CoreTranslator {
   }
 };
 
-// src/message/tokenize/parse-attributes.ts
+// src/message/tokenize/utils/extract-attributes.ts
 var ATTR_REGEX = /\s+([a-zA-Z_][a-zA-Z0-9_]*)="([^"]*)"/g;
-var parseAttributes = (input) => {
+var extractAttributes = (input) => {
   const attributes = {};
   let match;
   let consumed = "";
@@ -377,7 +377,7 @@ var tokenize = (message) => {
       const openMatch = message.slice(pos).match(OPEN_TAG_REGEX);
       if (openMatch) {
         const [, name, rawAttributes] = openMatch;
-        const attributes = parseAttributes(rawAttributes);
+        const attributes = extractAttributes(rawAttributes);
         if (attributes) {
           flushText();
           tokens.push({
@@ -409,7 +409,7 @@ var tokenize = (message) => {
   return tokens;
 };
 
-// src/message/build-ast/build-ast.ts
+// src/message/ast/build-ast.ts
 function buildAST(tokens) {
   const root = [];
   const stack = [];
@@ -464,4 +464,21 @@ function parseRichMessage(message) {
   return buildAST(tokens);
 }
 
-export { ScopeTranslator as Translator, parseRichMessage };
+// src/message/render/render.ts
+function render(nodes, renderer) {
+  return nodes.map((node) => {
+    if (node.type === "text") {
+      return renderer.text(node.value);
+    }
+    const children = render(node.children, renderer);
+    return renderer.tag(node.name, node.attributes, children);
+  });
+}
+
+// src/message/render-rich-message.ts
+function renderRichMessage(message, renderer) {
+  const nodes = parseRichMessage(message);
+  return render(nodes, renderer);
+}
+
+export { ScopeTranslator as Translator, parseRichMessage, renderRichMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-translator",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "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"