@octanejs/i18next 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2015-present i18next
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# @octanejs/i18next
+
+[react-i18next](https://github.com/i18next/react-i18next)'s binding layer for the
+[Octane](https://github.com/octanejs/octane) UI framework. It uses `i18next`
+unchanged and ports the context, hooks, `Trans`, ICU, HOC, and SSR integration to
+Octane.
+
+The runtime surface tracks `react-i18next@17.0.9`, so most migrations only change
+the package import:
+
+```diff
+- import { useTranslation, Trans } from 'react-i18next';
++ import { useTranslation, Trans } from '@octanejs/i18next';
+```
+
+## Install
+
+```bash
+pnpm add @octanejs/i18next i18next
+```
+
+Initialize i18next with the compatibility-named `initReactI18next` plugin. The
+name is retained so shared setup code and ecosystem integrations keep working.
+
+```ts
+import i18n from 'i18next';
+import { initReactI18next } from '@octanejs/i18next';
+
+await i18n.use(initReactI18next).init({
+  lng: 'en',
+  fallbackLng: 'en',
+  resources: {
+    en: {
+      translation: {
+        greeting: 'Hello {{name}}',
+        richGreeting: 'Hello <strong>{{name}}</strong>',
+      },
+    },
+  },
+  interpolation: { escapeValue: false },
+});
+```
+
+Provide an instance explicitly when an app can host more than one instance or
+when you want a scoped default namespace:
+
+```tsx
+import { I18nextProvider } from '@octanejs/i18next';
+
+export function Root() @{
+  <I18nextProvider i18n={i18n} defaultNS="translation">
+    <App />
+  </I18nextProvider>
+}
+```
+
+## Hooks and Suspense
+
+`useTranslation` has the same tuple and object shape as react-i18next and reacts
+to `languageChanged` and configured store events.
+
+```tsx
+import { useTranslation } from '@octanejs/i18next';
+
+export function Greeting(props: { name: string }) @{
+  const { t, ready, i18n } = useTranslation('translation');
+  <section>
+    <p>{t('greeting', { name: props.name }) as string}</p>
+    <button onClick={() => i18n.changeLanguage('fr')}>French</button>
+    <small>{String(ready)}</small>
+  </section>
+}
+```
+
+Suspense is enabled by default. Missing namespaces suspend through Octane's
+`use(thenable)` integration; set `useSuspense: false` and check `ready` when a
+non-suspending loading state is preferable.
+
+## Rich translations
+
+The most portable `Trans` form uses `defaults`/`values` and a component map:
+
+```tsx
+<Trans
+  i18nKey="richGreeting"
+  values={{ name: 'Ada' }}
+  components={{ strong: <strong class="emphasis" /> }}
+/>
+```
+
+There is one Octane-specific authoring rule. Natural `.tsrx` block children are
+compiled into an imperative render body, so `Trans` cannot inspect them to build
+its default string. Put inspectable children in prop position instead:
+
+```tsx
+<Trans
+  i18nKey="richGreeting"
+  children={<>
+    Hello
+    <strong>
+      {{ name: 'Ada' }}
+    </strong>
+  </>}
+/>
+```
+
+A natural block-child form renders its authored fallback and emits a development
+warning explaining this adaptation.
+
+`IcuTrans` and `IcuTransWithoutContext` support react-i18next's declaration-tree
+API:
+
+```tsx
+<IcuTrans
+  i18nKey="cta"
+  defaultTranslation="Read <0>the guide</0>"
+  content={[{ type: 'a', props: { href: '/guide' } }]}
+/>
+```
+
+## Server rendering
+
+Preload the namespaces needed for a request and render normally through
+`octane/server`. Namespace usage is collected on `i18n.reportNamespaces` for
+serialization into the client response.
+
+```ts
+import { renderToString } from 'octane/server';
+
+const { html, css } = renderToString(App, { i18n });
+const usedNamespaces = i18n.reportNamespaces?.getUsedNamespaces() ?? [];
+```
+
+`useSSR`, `withSSR`, `getInitialProps`, and `composeInitialProps` are retained for
+applications migrating an existing react-i18next SSR integration.
+
+## Supported surface and differences
+
+The root runtime export list matches `react-i18next@17.0.9`, including
+`Translation`, `withTranslation`, `TransWithoutContext`, `IcuTrans`, `useSSR`,
+`withSSR`, context/default helpers, and the ICU helper exports. Octane uses
+ref-as-prop semantics, so `withTranslation({ withRef: true })` does not use
+`forwardRef`. Class components are not supported.
+
+The Babel/React-specific `icu.macro` subpath is intentionally not included; use
+the runtime `IcuTrans` APIs. See the generated
+[bindings status](../../docs/bindings-status.md) for the current compatibility
+record.
+
+This package is derived from react-i18next and is distributed under the MIT
+license.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@octanejs/i18next",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "react-i18next for the octane renderer — reuses i18next unchanged and ports the React context, hooks, Trans, ICU, and SSR binding layer onto octane.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/i18next"
+  },
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./TransWithoutContext": {
+      "types": "./src/TransWithoutContext.d.ts",
+      "default": "./src/TransWithoutContext.js"
+    },
+    "./initReactI18next": {
+      "types": "./src/initReactI18next.d.ts",
+      "default": "./src/initReactI18next.js"
+    }
+  },
+  "dependencies": {
+    "html-parse-stringify": "^3.0.1"
+  },
+  "peerDependencies": {
+    "i18next": ">=26.2.0",
+    "octane": "0.1.5"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "i18next": "26.3.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-i18next": "17.0.9",
+    "vitest": "^4.1.9",
+    "octane": "0.1.5"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/I18nextProvider.js

@@ -0,0 +1,9 @@
+// Ported from react-i18next@17.0.9 (8b4a9ea): React primitives -> octane.
+import { createElement, useMemo } from 'octane';
+import { I18nContext } from './context.js';
+import { S } from './internal.js';
+
+export function I18nextProvider({ i18n, defaultNS, children }) {
+	const value = useMemo(() => ({ i18n, defaultNS }), [i18n, defaultNS], S('I18nextProvider:value'));
+	return createElement(I18nContext.Provider, { value }, children);
+}

package/src/IcuTrans.js

@@ -0,0 +1,104 @@
+// Ported from react-i18next@17.0.9 (8b4a9ea): React context -> octane context.
+import { useContext } from 'octane';
+import { IcuTransWithoutContext } from './IcuTransWithoutContext.js';
+import { getI18n, I18nContext } from './context.js';
+
+/**
+ * IcuTrans component for rendering ICU MessageFormat translations with React components
+ *
+ * This component provides a context-aware wrapper around IcuTransWithoutContext,
+ * automatically retrieving the i18n instance from React context when used within
+ * an I18nextProvider. It uses a declaration tree approach where components are
+ * defined as type + props blueprints, fetches the translated string, and reconstructs
+ * the React element tree by replacing numbered tags with actual components.
+ *
+ * Key features:
+ * - Supports React Context (I18nextProvider)
+ * - Falls back to global i18n instance
+ * - ICU MessageFormat compatible
+ * - Type-safe component declarations
+ * - Automatic HTML entity decoding
+ *
+ * @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
+ * @param {Object} [props.values] - Optional values for ICU variable interpolation
+ * @param {Object} [props.i18n] - Optional i18next instance (overrides context)
+ * @param {Function} [props.t] - Optional translation function (overrides context)
+ * @returns {React.ReactElement} React fragment containing the rendered translation
+ *
+ * @example
+ * ```jsx
+ * // Basic usage with context
+ * <I18nextProvider i18n={i18n}>
+ *   <IcuTrans
+ *     i18nKey="welcome.message"
+ *     defaultTranslation="Welcome <0>friend</0>!"
+ *     content={[
+ *       { type: 'strong', props: { className: 'highlight' } }
+ *     ]}
+ *   />
+ * </I18nextProvider>
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // With custom components and nested structure
+ * <IcuTrans
+ *   i18nKey="docs.link"
+ *   defaultTranslation="Read the <0>documentation <1></1></0> for more info"
+ *   content={[
+ *     { type: 'a', props: { href: '/docs' } },
+ *     { type: Icon, props: { name: 'external' } }
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // With nested children in declarations
+ * <IcuTrans
+ *   i18nKey="list.items"
+ *   defaultTranslation="<0><0>First item</0><1>Second item</1></0>"
+ *   content={[
+ *     {
+ *       type: 'ul',
+ *       props: {
+ *         children: [
+ *           { type: 'li', props: {} },
+ *           { type: 'li', props: {} }
+ *         ]
+ *       }
+ *     }
+ *   ]}
+ * />
+ * ```
+ */
+export function IcuTrans({
+	i18nKey,
+	defaultTranslation,
+	content,
+	ns,
+	values = {},
+	i18n: i18nFromProps,
+	t: tFromProps,
+}) {
+	const { i18n: i18nFromContext, defaultNS: defaultNSFromContext } = useContext(I18nContext) || {};
+	const i18n = i18nFromProps || i18nFromContext || getI18n();
+
+	const t = tFromProps || i18n?.t.bind(i18n);
+
+	return IcuTransWithoutContext({
+		i18nKey,
+		defaultTranslation,
+		content,
+		ns: ns || t?.ns || defaultNSFromContext || i18n?.options?.defaultNS,
+		values,
+		i18n,
+		t: tFromProps,
+	});
+}
+
+IcuTrans.displayName = 'IcuTrans';

package/src/IcuTransUtils/TranslationParserError.js

@@ -0,0 +1,24 @@
+/**
+ * Error thrown during translation parsing
+ */
+export class TranslationParserError extends Error {
+	/**
+	 * @param {string} message - Error message
+	 * @param {number} [position] - Position in the translation string where the error occurred
+	 * @param {string} [translationString] - The full translation string being parsed
+	 */
+	constructor(message, position, translationString) {
+		super(message);
+
+		this.name = 'TranslationParserError';
+
+		this.position = position;
+
+		this.translationString = translationString;
+
+		// Maintains proper stack trace for where our error was thrown (only available on V8)
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, TranslationParserError);
+		}
+	}
+}

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.js';
+export * from './htmlEntityDecoder.js';
+export * from './tokenizer.js';
+export * from './renderTranslation.js';