@octanejs/i18next 0.1.0

package/src/IcuTransUtils/renderTranslation.js

@@ -0,0 +1,216 @@
+// Ported from react-i18next@17.0.9 (8b4a9ea): declarations produce octane descriptors.
+import { createElement, positionalChildren } from 'octane';
+
+import { TranslationParserError } from './TranslationParserError.js';
+import { tokenize } from './tokenizer.js';
+import { decodeHtmlEntities } from './htmlEntityDecoder.js';
+
+/**
+ * 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 createElement(type, propsWithoutChildren, ...children);
+	}
+
+	// Standard rendering with children from translation
+	if (children.length === 0) {
+		return createElement(type, props);
+	}
+	if (children.length === 1) {
+		return createElement(type, props, children[0]);
+	}
+	return 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 positionalChildren(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,147 @@
+// Ported from react-i18next@17.0.9 (8b4a9ea): dynamic nodes are octane descriptors.
+import { warn, warnOnce, isString } from './utils.js';
+import { getI18n } from './i18nInstance.js';
+import { renderTranslation } from './IcuTransUtils/index.js';
+
+/**
+ * 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 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);
+
+		// Octane components may return an array directly; Fragment is a
+		// compiler sentinel rather than a runtime component constructor.
+		return 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 translation;
+	}
+}
+
+IcuTransWithoutContext.displayName = 'IcuTransWithoutContext';

package/src/Trans.js

@@ -0,0 +1,46 @@
+// Ported from react-i18next@17.0.9 (8b4a9ea): React context -> octane context.
+import { useContext } from 'octane';
+import { nodesToString, Trans as TransWithoutContext } from './TransWithoutContext.js';
+import { getI18n, I18nContext } from './context.js';
+
+export { nodesToString };
+
+export function Trans({
+	children,
+	count,
+	parent,
+	i18nKey,
+	context,
+	tOptions = {},
+	values,
+	defaults,
+	components,
+	ns,
+	i18n: i18nFromProps,
+	t: tFromProps,
+	shouldUnescape,
+	...additionalProps
+}) {
+	const { i18n: i18nFromContext, defaultNS: defaultNSFromContext } = useContext(I18nContext) || {};
+	const i18n = i18nFromProps || i18nFromContext || getI18n();
+
+	const t = tFromProps || i18n?.t.bind(i18n);
+
+	return TransWithoutContext({
+		children,
+		count,
+		parent,
+		i18nKey,
+		context,
+		tOptions,
+		values,
+		defaults,
+		components,
+		// prepare having a namespace
+		ns: ns || t?.ns || defaultNSFromContext || i18n?.options?.defaultNS,
+		i18n,
+		t: tFromProps,
+		shouldUnescape,
+		...additionalProps,
+	});
+}

package/src/TransWithoutContext.d.ts

@@ -0,0 +1,160 @@
+import type {
+	i18n,
+	ReactOptions,
+	ApplyTarget,
+	ConstrainTarget,
+	GetSource,
+	InterpolationMap,
+	ParseKeys,
+	Namespace,
+	SelectorFn,
+	SelectorKey,
+	TFunctionReturn,
+	TypeOptions,
+	TOptions,
+	TFunction,
+} from 'i18next';
+import type { ComponentBody, ElementDescriptor } from 'octane';
+
+type _DefaultNamespace = TypeOptions['defaultNS'];
+type _EnableSelector = TypeOptions['enableSelector'];
+type _KeySeparator = TypeOptions['keySeparator'];
+type _AppendKeyPrefix<Key, KPrefix> = KPrefix extends string
+	? `${KPrefix}${_KeySeparator}${Key & string}`
+	: Key;
+
+type TransChild = unknown;
+type $NoInfer<T> = [T][T extends T ? 0 : never];
+
+export type TransProps<
+	Key extends ParseKeys<Ns, TOpt, KPrefix>,
+	Ns extends Namespace = _DefaultNamespace,
+	KPrefix = undefined,
+	TContext extends string | undefined = undefined,
+	TOpt extends TOptions & { context?: TContext } = { context: TContext },
+	Ret = TFunctionReturn<Ns, _AppendKeyPrefix<Key, KPrefix>, TOpt>,
+	E = Record<string, unknown>,
+> = E & {
+	children?: TransChild | readonly TransChild[];
+	components?: readonly ElementDescriptor[] | { readonly [tagName: string]: ElementDescriptor };
+	count?: number;
+	context?: TContext;
+	defaults?: string;
+	i18n?: i18n;
+	i18nKey?: Key | Key[];
+	// allow a single namespace from an array-typed `t` (e.g. useTranslation(['ns'])); TS7 intersects
+	// inference candidates from `t` and `ns`, so a bare `Ns` here rejects ns="ns" when t is passed
+	ns?: Ns | (Ns extends readonly (infer S extends string)[] ? S : never);
+	parent?: string | ComponentBody<any> | null;
+	tOptions?: TOpt;
+	values?: InterpolationMap<Ret>;
+	shouldUnescape?: boolean;
+	t?: TFunction<Ns, KPrefix>;
+};
+
+export interface TransLegacy {
+	<
+		const Key extends ParseKeys<Ns, TOpt, KPrefix>,
+		Ns extends Namespace = _DefaultNamespace,
+		KPrefix = undefined,
+		TContext extends string | undefined = undefined,
+		TOpt extends TOptions & { context?: TContext } = { context: TContext },
+		Ret extends TFunctionReturn<Ns, _AppendKeyPrefix<Key, KPrefix>, TOpt> = TFunctionReturn<
+			Ns,
+			_AppendKeyPrefix<Key, KPrefix>,
+			TOpt
+		>,
+		E = Record<string, unknown>,
+	>(
+		props: TransProps<Key, Ns, KPrefix, TContext, TOpt, Ret, E>,
+	): unknown;
+}
+
+export interface TransSelectorProps<
+	Key,
+	Ns extends Namespace = _DefaultNamespace,
+	KPrefix = undefined,
+	TContext extends string | undefined = undefined,
+	TOpt extends TOptions & { context?: TContext } = { context: TContext },
+> {
+	children?: TransChild | readonly TransChild[];
+	components?: readonly ElementDescriptor[] | { readonly [tagName: string]: ElementDescriptor };
+	count?: number;
+	context?: TContext;
+	defaults?: string | Key;
+	i18n?: i18n;
+	i18nKey?: Key | readonly Key[];
+	// see TransProps.ns: keep single-namespace values assignable when `t` fixes Ns to an array
+	ns?: Ns | (Ns extends readonly (infer S extends string)[] ? S : never);
+	parent?: string | ComponentBody<any> | null;
+	tOptions?: TOpt;
+	values?: Key extends (...args: any[]) => infer R ? InterpolationMap<R> : {};
+	shouldUnescape?: boolean;
+	t?: TFunction<Ns, KPrefix>;
+}
+
+export interface TransSelector {
+	<
+		Target extends ConstrainTarget<TOpt>,
+		Key extends
+			| SelectorFn<GetSource<$NoInfer<Ns>, KPrefix>, ApplyTarget<Target, TOpt>, TOpt>
+			| SelectorKey,
+		const Ns extends Namespace = _DefaultNamespace,
+		KPrefix = undefined,
+		TContext extends string | undefined = undefined,
+		TOpt extends TOptions & { context?: TContext } = { context: TContext },
+		E = Record<string, unknown>,
+	>(
+		props: TransSelectorProps<Key, Ns, KPrefix, TContext, TOpt> & E,
+	): unknown;
+}
+
+export const Trans: _EnableSelector extends true | 'optimize' | 'strict'
+	? TransSelector
+	: TransLegacy;
+
+export function nodesToString(
+	children: unknown,
+	i18nOptions?: ReactOptions,
+	i18n?: i18n,
+	i18nKey?: string,
+): string;
+
+export type ErrorCode =
+	| 'NO_I18NEXT_INSTANCE'
+	| 'NO_LANGUAGES'
+	| 'DEPRECATED_OPTION'
+	| 'TRANS_NULL_VALUE'
+	| 'TRANS_INVALID_OBJ'
+	| 'TRANS_INVALID_VAR'
+	| 'TRANS_INVALID_COMPONENTS'
+	| 'USE_T_BEFORE_READY'
+	| 'OCTANE_TRANS_BLOCK_CHILDREN'
+	| 'ICU_TRANS_RENDER_ERROR';
+
+export type ErrorMeta = {
+	code: ErrorCode;
+	i18nKey?: string;
+	[x: string]: any;
+};
+
+/**
+ * Use to type the logger arguments
+ * @example
+ * ```
+ * import type { ErrorArgs } from 'react-i18next';
+ *
+ * const logger = {
+ *   // ....
+ *   warn: function (...args: ErrorArgs) {
+ *      if (args[1]?.code === 'TRANS_INVALID_OBJ') {
+ *        const [msg, { i18nKey, ...rest }] = args;
+ *        return log(i18nKey, msg, rest);
+ *      }
+ *      log(...args);
+ *   }
+ * }
+ * i18n.use(logger).use(i18nReactPlugin).init({...});
+ * ```
+ */
+export type ErrorArgs = readonly [string, ErrorMeta | undefined, ...any[]];