react-i18next 16.0.1 → 16.1.0

package/src/IcuTransUtils/htmlEntityDecoder.js

@@ -0,0 +1,264 @@
+/**
+ * Common HTML entities map for fast lookup
+ */
+const commonEntities = {
+  // Basic entities
+  ' ': '\u00A0', // Non-breaking space
+  '&': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&apos;': "'",
+
+  // Copyright, trademark, and registration
+  '&copy;': '©',
+  '&reg;': '®',
+  '&trade;': '™',
+
+  // Punctuation
+  '&hellip;': '…',
+  '&ndash;': '–',
+  '&mdash;': '—',
+  '&lsquo;': '\u2018',
+  '&rsquo;': '\u2019',
+  '&sbquo;': '\u201A',
+  '&ldquo;': '\u201C',
+  '&rdquo;': '\u201D',
+  '&bdquo;': '\u201E',
+  '&dagger;': '†',
+  '&Dagger;': '‡',
+  '&bull;': '•',
+  '&prime;': '′',
+  '&Prime;': '″',
+  '&lsaquo;': '‹',
+  '&rsaquo;': '›',
+  '&sect;': '§',
+  '&para;': '¶',
+  '&middot;': '·',
+
+  // Spaces
+  '&ensp;': '\u2002',
+  '&emsp;': '\u2003',
+  '&thinsp;': '\u2009',
+
+  // Currency
+  '&euro;': '€',
+  '&pound;': '£',
+  '&yen;': '¥',
+  '&cent;': '¢',
+  '&curren;': '¤',
+
+  // Math symbols
+  '&times;': '×',
+  '&divide;': '÷',
+  '&minus;': '−',
+  '&plusmn;': '±',
+  '&ne;': '≠',
+  '&le;': '≤',
+  '&ge;': '≥',
+  '&asymp;': '≈',
+  '&equiv;': '≡',
+  '&infin;': '∞',
+  '&int;': '∫',
+  '&sum;': '∑',
+  '&prod;': '∏',
+  '&radic;': '√',
+  '&part;': '∂',
+  '&permil;': '‰',
+  '&deg;': '°',
+  '&micro;': 'µ',
+
+  // Arrows
+  '&larr;': '←',
+  '&uarr;': '↑',
+  '&rarr;': '→',
+  '&darr;': '↓',
+  '&harr;': '↔',
+  '&crarr;': '↵',
+  '&lArr;': '⇐',
+  '&uArr;': '⇑',
+  '&rArr;': '⇒',
+  '&dArr;': '⇓',
+  '&hArr;': '⇔',
+
+  // Greek letters (lowercase)
+  '&alpha;': 'α',
+  '&beta;': 'β',
+  '&gamma;': 'γ',
+  '&delta;': 'δ',
+  '&epsilon;': 'ε',
+  '&zeta;': 'ζ',
+  '&eta;': 'η',
+  '&theta;': 'θ',
+  '&iota;': 'ι',
+  '&kappa;': 'κ',
+  '&lambda;': 'λ',
+  '&mu;': 'μ',
+  '&nu;': 'ν',
+  '&xi;': 'ξ',
+  '&omicron;': 'ο',
+  '&pi;': 'π',
+  '&rho;': 'ρ',
+  '&sigma;': 'σ',
+  '&tau;': 'τ',
+  '&upsilon;': 'υ',
+  '&phi;': 'φ',
+  '&chi;': 'χ',
+  '&psi;': 'ψ',
+  '&omega;': 'ω',
+
+  // Greek letters (uppercase)
+  '&Alpha;': 'Α',
+  '&Beta;': 'Β',
+  '&Gamma;': 'Γ',
+  '&Delta;': 'Δ',
+  '&Epsilon;': 'Ε',
+  '&Zeta;': 'Ζ',
+  '&Eta;': 'Η',
+  '&Theta;': 'Θ',
+  '&Iota;': 'Ι',
+  '&Kappa;': 'Κ',
+  '&Lambda;': 'Λ',
+  '&Mu;': 'Μ',
+  '&Nu;': 'Ν',
+  '&Xi;': 'Ξ',
+  '&Omicron;': 'Ο',
+  '&Pi;': 'Π',
+  '&Rho;': 'Ρ',
+  '&Sigma;': 'Σ',
+  '&Tau;': 'Τ',
+  '&Upsilon;': 'Υ',
+  '&Phi;': 'Φ',
+  '&Chi;': 'Χ',
+  '&Psi;': 'Ψ',
+  '&Omega;': 'Ω',
+
+  // Latin extended
+  '&Agrave;': 'À',
+  '&Aacute;': 'Á',
+  '&Acirc;': 'Â',
+  '&Atilde;': 'Ã',
+  '&Auml;': 'Ä',
+  '&Aring;': 'Å',
+  '&AElig;': 'Æ',
+  '&Ccedil;': 'Ç',
+  '&Egrave;': 'È',
+  '&Eacute;': 'É',
+  '&Ecirc;': 'Ê',
+  '&Euml;': 'Ë',
+  '&Igrave;': 'Ì',
+  '&Iacute;': 'Í',
+  '&Icirc;': 'Î',
+  '&Iuml;': 'Ï',
+  '&ETH;': 'Ð',
+  '&Ntilde;': 'Ñ',
+  '&Ograve;': 'Ò',
+  '&Oacute;': 'Ó',
+  '&Ocirc;': 'Ô',
+  '&Otilde;': 'Õ',
+  '&Ouml;': 'Ö',
+  '&Oslash;': 'Ø',
+  '&Ugrave;': 'Ù',
+  '&Uacute;': 'Ú',
+  '&Ucirc;': 'Û',
+  '&Uuml;': 'Ü',
+  '&Yacute;': 'Ý',
+  '&THORN;': 'Þ',
+  '&szlig;': 'ß',
+  '&agrave;': 'à',
+  '&aacute;': 'á',
+  '&acirc;': 'â',
+  '&atilde;': 'ã',
+  '&auml;': 'ä',
+  '&aring;': 'å',
+  '&aelig;': 'æ',
+  '&ccedil;': 'ç',
+  '&egrave;': 'è',
+  '&eacute;': 'é',
+  '&ecirc;': 'ê',
+  '&euml;': 'ë',
+  '&igrave;': 'ì',
+  '&iacute;': 'í',
+  '&icirc;': 'î',
+  '&iuml;': 'ï',
+  '&eth;': 'ð',
+  '&ntilde;': 'ñ',
+  '&ograve;': 'ò',
+  '&oacute;': 'ó',
+  '&ocirc;': 'ô',
+  '&otilde;': 'õ',
+  '&ouml;': 'ö',
+  '&oslash;': 'ø',
+  '&ugrave;': 'ù',
+  '&uacute;': 'ú',
+  '&ucirc;': 'û',
+  '&uuml;': 'ü',
+  '&yacute;': 'ý',
+  '&thorn;': 'þ',
+  '&yuml;': 'ÿ',
+
+  // Special characters
+  '&iexcl;': '¡',
+  '&iquest;': '¿',
+  '&fnof;': 'ƒ',
+  '&circ;': 'ˆ',
+  '&tilde;': '˜',
+  '&OElig;': 'Œ',
+  '&oelig;': 'œ',
+  '&Scaron;': 'Š',
+  '&scaron;': 'š',
+  '&Yuml;': 'Ÿ',
+  '&ordf;': 'ª',
+  '&ordm;': 'º',
+  '&macr;': '¯',
+  '&acute;': '´',
+  '&cedil;': '¸',
+  '&sup1;': '¹',
+  '&sup2;': '²',
+  '&sup3;': '³',
+  '&frac14;': '¼',
+  '&frac12;': '½',
+  '&frac34;': '¾',
+
+  // Card suits
+  '&spades;': '♠',
+  '&clubs;': '♣',
+  '&hearts;': '♥',
+  '&diams;': '♦',
+
+  // Miscellaneous
+  '&loz;': '◊',
+  '&oline;': '‾',
+  '&frasl;': '⁄',
+  '&weierp;': '℘',
+  '&image;': 'ℑ',
+  '&real;': 'ℜ',
+  '&alefsym;': 'ℵ',
+};
+
+// Create regex pattern for all entities
+const entityPattern = new RegExp(
+  Object.keys(commonEntities)
+    .map((entity) => entity.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|'),
+  'g',
+);
+
+/**
+ * Decode HTML entities in text
+ *
+ * Uses a hybrid approach:
+ * 1. First pass: decode common named entities using a map
+ * 2. Second pass: decode numeric entities (decimal and hexadecimal)
+ *
+ * @param {string} text - Text with HTML entities
+ * @returns {string} Decoded text
+ */
+export const decodeHtmlEntities = (text) =>
+  text
+    // First pass: common named entities
+    .replace(entityPattern, (match) => commonEntities[match])
+    // Second pass: numeric entities (decimal)
+    .replace(/&#(\d+);/g, (_, num) => String.fromCharCode(parseInt(num, 10)))
+    // Third pass: numeric entities (hexadecimal)
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));

package/src/IcuTransUtils/index.js

@@ -0,0 +1,4 @@
+export * from './TranslationParserError';
+export * from './htmlEntityDecoder';
+export * from './tokenizer';
+export * from './renderTranslation';

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;
+};