react-i18next 16.0.0 → 16.1.0

package/src/IcuTransUtils/renderTranslation.js

@@ -0,0 +1,215 @@
+import React from 'react';
+
+import { TranslationParserError } from './TranslationParserError';
+import { tokenize } from './tokenizer';
+import { decodeHtmlEntities } from './htmlEntityDecoder';
+
+/**
+ * Render a React element tree from a declaration node and its children
+ *
+ * @param {Object} declaration - The component declaration (type + props)
+ * @param {Array<React.ReactNode>} children - Array of child nodes (text, numbers, React elements)
+ * @param {Array<Object>} [childDeclarations] - Optional array of child declarations to use for nested rendering
+ * @returns {React.ReactElement} A React element
+ */
+const renderDeclarationNode = (declaration, children, childDeclarations) => {
+  const { type, props = {} } = declaration;
+
+  // If props contain a children declaration AND we have childDeclarations to work with,
+  // we need to recursively render the content with those child declarations
+  if (props.children && Array.isArray(props.children) && childDeclarations) {
+    // The children array contains the parsed content from inside this tag
+    // We need to rebuild the translation string and re-parse it with child declarations
+    // For now, we'll use the children directly as they're already parsed
+    // This happens when renderTranslation is called recursively
+
+    // Remove children from props since we'll pass them as the third argument
+    // eslint-disable-next-line no-unused-vars
+    const { children: _childrenToRemove, ...propsWithoutChildren } = props;
+
+    return React.createElement(type, propsWithoutChildren, ...children);
+  }
+
+  // Standard rendering with children from translation
+  if (children.length === 0) {
+    return React.createElement(type, props);
+  }
+  if (children.length === 1) {
+    return React.createElement(type, props, children[0]);
+  }
+  return React.createElement(type, props, ...children);
+};
+
+/**
+ * Render translation string with declaration tree to create React elements
+ *
+ * This function parses an ICU format translation string and reconstructs
+ * a React element tree using the provided declaration tree. It replaces
+ * numbered tags (e.g., <0>, <1>) with the corresponding components from
+ * the declaration array and fills them with the translated text.
+ *
+ * @param {string} translation - ICU format string (e.g., "<0>Click here</0>")
+ * @param {Array<Object>} [declarations=[]] - Array of component declarations matching tag numbers
+ * @returns {Array<React.ReactNode>} Array of React nodes (elements and text)
+ *
+ * @example
+ * ```jsx
+ * const result = renderTranslation(
+ *   "<0>bonjour</0> monde",
+ *   [{ type: 'strong', props: { className: 'bold' } }]
+ * );
+ * // Returns: [<strong className="bold">bonjour</strong>, " monde"]
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // With nested children in declaration
+ * const result = renderTranslation(
+ *   "<0>Click <1>here</1></0>",
+ *   [
+ *     {
+ *       type: 'div',
+ *       props: {
+ *         children: [{ type: 'span', props: {} }]
+ *       }
+ *     }
+ *   ]
+ * );
+ * ```
+ */
+export const renderTranslation = (translation, declarations = []) => {
+  if (!translation) {
+    return [];
+  }
+
+  const tokens = tokenize(translation);
+  const result = [];
+  const stack = [];
+
+  // Track tag numbers that should be treated as literal text (no declaration found)
+  const literalTagNumbers = new Set();
+
+  // Helper to get the current declarations array based on context
+  const getCurrentDeclarations = () => {
+    if (stack.length === 0) {
+      return declarations;
+    }
+
+    const parentFrame = stack[stack.length - 1];
+
+    // If the parent declaration has children declarations, use those
+    if (
+      parentFrame.declaration.props?.children &&
+      Array.isArray(parentFrame.declaration.props.children)
+    ) {
+      return parentFrame.declaration.props.children;
+    }
+
+    // Otherwise, use the parent's declarations array
+    return parentFrame.declarations;
+  };
+
+  tokens.forEach((token) => {
+    // eslint-disable-next-line default-case
+    switch (token.type) {
+      case 'Text':
+        {
+          const decoded = decodeHtmlEntities(token.value);
+          const targetArray = stack.length > 0 ? stack[stack.length - 1].children : result;
+
+          targetArray.push(decoded);
+        }
+
+        break;
+
+      case 'TagOpen':
+        {
+          const { tagNumber } = token;
+          const currentDeclarations = getCurrentDeclarations();
+          const declaration = currentDeclarations[tagNumber];
+
+          if (!declaration) {
+            // No declaration found - treat this tag as literal text
+            literalTagNumbers.add(tagNumber);
+
+            const literalText = `<${tagNumber}>`;
+            const targetArray = stack.length > 0 ? stack[stack.length - 1].children : result;
+
+            targetArray.push(literalText);
+
+            break;
+          }
+
+          stack.push({
+            tagNumber,
+            children: [],
+            position: token.position,
+            declaration,
+            declarations: currentDeclarations,
+          });
+        }
+
+        break;
+
+      case 'TagClose':
+        {
+          const { tagNumber } = token;
+
+          // If this tag was treated as literal, output the closing tag as literal text
+          if (literalTagNumbers.has(tagNumber)) {
+            const literalText = `</${tagNumber}>`;
+            const literalTargetArray = stack.length > 0 ? stack[stack.length - 1].children : result;
+
+            literalTargetArray.push(literalText);
+
+            literalTagNumbers.delete(tagNumber);
+
+            break;
+          }
+
+          if (stack.length === 0) {
+            throw new TranslationParserError(
+              `Unexpected closing tag </${tagNumber}> at position ${token.position}`,
+              token.position,
+              translation,
+            );
+          }
+
+          const frame = stack.pop();
+
+          if (frame.tagNumber !== tagNumber) {
+            throw new TranslationParserError(
+              `Mismatched tags: expected </${frame.tagNumber}> but got </${tagNumber}> at position ${token.position}`,
+              token.position,
+              translation,
+            );
+          }
+
+          // Render the element using the declaration and collected children
+          const element = renderDeclarationNode(
+            frame.declaration,
+            frame.children,
+            frame.declarations,
+          );
+
+          const elementTargetArray = stack.length > 0 ? stack[stack.length - 1].children : result;
+
+          elementTargetArray.push(element);
+        }
+
+        break;
+    }
+  });
+
+  if (stack.length > 0) {
+    const unclosed = stack[stack.length - 1];
+
+    throw new TranslationParserError(
+      `Unclosed tag <${unclosed.tagNumber}> at position ${unclosed.position}`,
+      unclosed.position,
+      translation,
+    );
+  }
+
+  return result;
+};

package/src/IcuTransUtils/tokenizer.js

@@ -0,0 +1,78 @@
+/**
+ * Tokenize a translation string with numbered tags
+ * Note: Variables are already interpolated by the i18n system before we receive the string
+ *
+ * @param {string} translation - Translation string with numbered tags
+ * @returns {Array<Token>} Array of tokens
+ */
+export const tokenize = (translation) => {
+  const tokens = [];
+
+  let position = 0;
+
+  let currentText = '';
+
+  const flushText = () => {
+    if (currentText) {
+      tokens.push({
+        type: 'Text',
+        value: currentText,
+        position: position - currentText.length,
+      });
+
+      currentText = '';
+    }
+  };
+
+  while (position < translation.length) {
+    const char = translation[position];
+
+    // Check for opening tag: <0>, <1>, etc.
+    if (char === '<') {
+      const tagMatch = translation.slice(position).match(/^<(\d+)>/);
+
+      if (tagMatch) {
+        flushText();
+
+        tokens.push({
+          type: 'TagOpen',
+          value: tagMatch[0],
+          position,
+          tagNumber: parseInt(tagMatch[1], 10),
+        });
+
+        position += tagMatch[0].length;
+      } else {
+        // Check for closing tag: </0>, </1>, etc.
+        const closeTagMatch = translation.slice(position).match(/^<\/(\d+)>/);
+
+        if (closeTagMatch) {
+          flushText();
+
+          tokens.push({
+            type: 'TagClose',
+            value: closeTagMatch[0],
+            position,
+            tagNumber: parseInt(closeTagMatch[1], 10),
+          });
+
+          position += closeTagMatch[0].length;
+        } else {
+          // Regular text (including any { } characters that aren't our tags)
+          currentText += char;
+
+          position += 1;
+        }
+      }
+    } else {
+      // Regular text (including any { } characters that aren't our tags)
+      currentText += char;
+
+      position += 1;
+    }
+  }
+
+  flushText();
+
+  return tokens;
+};

package/src/IcuTransWithoutContext.js

@@ -0,0 +1,146 @@
+import React from 'react';
+import { warn, warnOnce, isString } from './utils.js';
+import { getI18n } from './i18nInstance.js';
+import { renderTranslation } from './IcuTransUtils';
+
+/**
+ * IcuTrans component for rendering ICU MessageFormat translations (without React Context)
+ *
+ * This is the core implementation without React hooks or context dependencies,
+ * making it suitable for use in any environment. It uses a declaration tree
+ * approach where components are defined as type + props blueprints, fetches
+ * the translated string via i18next, and reconstructs the React element tree
+ * by replacing numbered tags (<0>, <1>) with actual components.
+ *
+ * Key features:
+ * - No React hooks or context (can be used anywhere)
+ * - ICU MessageFormat compatible
+ * - Supports nested component declarations
+ * - Automatic HTML entity decoding
+ * - Graceful error handling with fallbacks
+ * - Merges default interpolation variables
+ *
+ * Note: Users should typically use the IcuTrans export which provides automatic
+ * context support. This component is exposed for advanced use cases where direct
+ * i18n instance control is needed, or for use outside of React Context.
+ *
+ * @param {Object} props - Component props
+ * @param {string} props.i18nKey - The i18n key to look up the translation
+ * @param {string} props.defaultTranslation - The default translation in ICU format with numbered tags (e.g., "<0>Click here</0>")
+ * @param {Array<{type: string|React.ComponentType, props?: Object}>} props.content - Declaration tree describing React components and their props
+ * @param {string|string[]} [props.ns] - Optional namespace(s) for the translation. Falls back to t.ns, then i18n.options.defaultNS, then 'translation'
+ * @param {Object} [props.values={}] - Optional values for ICU variable interpolation (merged with i18n.options.interpolation.defaultVariables if present)
+ * @param {Object} [props.i18n] - i18next instance. If not provided, uses global instance from getI18n()
+ * @param {Function} [props.t] - Custom translation function. If not provided, uses i18n.t.bind(i18n)
+ * @returns {React.ReactElement} React fragment containing the rendered translation
+ *
+ * @example
+ * ```jsx
+ * // Direct usage with i18n instance
+ * <IcuTransWithoutContext
+ *   i18nKey="welcome.message"
+ *   defaultTranslation="Welcome <0>back</0>!"
+ *   content={[
+ *     { type: 'strong', props: { className: 'highlight' } }
+ *   ]}
+ *   i18n={i18nInstance}
+ * />
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // With nested declarations for list rendering
+ * <IcuTransWithoutContext
+ *   i18nKey="features.list"
+ *   defaultTranslation="Features: <0><0>Fast</0><1>Reliable</1><2>Secure</2></0>"
+ *   content={[
+ *     {
+ *       type: 'ul',
+ *       props: {
+ *         children: [
+ *           { type: 'li', props: {} },
+ *           { type: 'li', props: {} },
+ *           { type: 'li', props: {} }
+ *         ]
+ *       }
+ *     }
+ *   ]}
+ *   i18n={i18nInstance}
+ * />
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // With values for ICU variable interpolation
+ * <IcuTransWithoutContext
+ *   i18nKey="greeting"
+ *   defaultTranslation="Hello <0>{name}</0>!"
+ *   content={[{ type: 'strong', props: {} }]}
+ *   values={{ name: 'Alice' }}
+ *   i18n={i18nInstance}
+ * />
+ * ```
+ */
+export function IcuTransWithoutContext({
+  i18nKey,
+  defaultTranslation,
+  content,
+  ns,
+  values = {},
+  i18n: i18nFromProps,
+  t: tFromProps,
+}) {
+  const i18n = i18nFromProps || getI18n();
+
+  if (!i18n) {
+    warnOnce(
+      i18n,
+      'NO_I18NEXT_INSTANCE',
+      `IcuTrans: You need to pass in an i18next instance using i18nextReactModule`,
+      { i18nKey },
+    );
+    return React.createElement(React.Fragment, {}, defaultTranslation);
+  }
+
+  const t = tFromProps || i18n.t?.bind(i18n) || ((k) => k);
+
+  // prepare having a namespace
+  let namespaces = ns || t.ns || i18n.options?.defaultNS;
+  namespaces = isString(namespaces) ? [namespaces] : namespaces || ['translation'];
+
+  // Merge default interpolation variables if they exist
+  let mergedValues = values;
+  if (i18n.options?.interpolation?.defaultVariables) {
+    mergedValues =
+      values && Object.keys(values).length > 0
+        ? { ...values, ...i18n.options.interpolation.defaultVariables }
+        : { ...i18n.options.interpolation.defaultVariables };
+  }
+
+  // Get the translation, falling back to defaultTranslation
+  const translation = t(i18nKey, {
+    defaultValue: defaultTranslation,
+    ...mergedValues,
+    ns: namespaces,
+  });
+
+  // Render the translation with the declaration tree
+  try {
+    const rendered = renderTranslation(translation, content);
+
+    // Return as a React fragment to avoid extra wrapper
+    return React.createElement(React.Fragment, {}, ...rendered);
+  } catch (error) {
+    // If rendering fails, warn and fall back to the translation string
+    warn(
+      i18n,
+      'ICU_TRANS_RENDER_ERROR',
+      `IcuTrans component error for key "${i18nKey}": ${error.message}`,
+      { i18nKey, error },
+    );
+
+    return React.createElement(React.Fragment, {}, translation);
+  }
+}
+
+IcuTransWithoutContext.displayName = 'IcuTransWithoutContext';

package/src/TransWithoutContext.js

@@ -1,4 +1,5 @@
 import { Fragment, isValidElement, cloneElement, createElement, Children } from 'react';
+import { keyFromSelector } from 'i18next';
 import HTML from 'html-parse-stringify';
 import { isObject, isString, warn, warnOnce } from './utils.js';
 import { getDefaults } from './defaults.js';
@@ -424,7 +425,10 @@ export function Trans({
 
   const nodeAsString = nodesToString(children, reactI18nextOptions, i18n, i18nKey);
   const defaultValue =
-    defaults || nodeAsString || reactI18nextOptions.transEmptyNodeValue || i18nKey;
+    defaults ||
+    nodeAsString ||
+    reactI18nextOptions.transEmptyNodeValue ||
+    (typeof i18nKey === 'function' ? keyFromSelector(i18nKey) : i18nKey);
   const { hashTransKey } = reactI18nextOptions;
   const key =
     i18nKey ||