@octanejs/i18next 0.1.0

package/src/context.js

@@ -0,0 +1,61 @@
+// Ported from react-i18next@17.0.9 (8b4a9ea): React context -> octane context.
+import { createContext } from 'octane';
+import { getDefaults, setDefaults } from './defaults.js';
+import { getI18n, setI18n } from './i18nInstance.js';
+import { initReactI18next } from './initReactI18next.js';
+
+export { getDefaults, setDefaults, getI18n, setI18n, initReactI18next };
+
+export const I18nContext = createContext();
+
+export class ReportNamespaces {
+	constructor() {
+		this.usedNamespaces = {};
+	}
+
+	addUsedNamespaces(namespaces) {
+		namespaces.forEach((ns) => {
+			if (!this.usedNamespaces[ns]) this.usedNamespaces[ns] = true;
+		});
+	}
+
+	getUsedNamespaces() {
+		return Object.keys(this.usedNamespaces);
+	}
+}
+
+export const composeInitialProps = (ForComponent) => async (ctx) => {
+	const componentsInitialProps = (await ForComponent.getInitialProps?.(ctx)) ?? {};
+
+	const i18nInitialProps = getInitialProps();
+
+	return {
+		...componentsInitialProps,
+		...i18nInitialProps,
+	};
+};
+
+export const getInitialProps = () => {
+	const i18n = getI18n();
+	if (!i18n) {
+		console.warn(
+			'react-i18next:: getInitialProps: You will need to pass in an i18next instance by using initReactI18next',
+		);
+		return {};
+	}
+	const namespaces = i18n.reportNamespaces?.getUsedNamespaces() ?? [];
+
+	const ret = {};
+	const initialI18nStore = {};
+	i18n.languages.forEach((l) => {
+		initialI18nStore[l] = {};
+		namespaces.forEach((ns) => {
+			initialI18nStore[l][ns] = i18n.getResourceBundle(l, ns) || {};
+		});
+	});
+
+	ret.initialI18nStore = initialI18nStore;
+	ret.initialLanguage = i18n.language;
+
+	return ret;
+};

package/src/defaults.js

@@ -0,0 +1,21 @@
+import { unescape } from './unescape.js';
+
+let defaultOptions = {
+	bindI18n: 'languageChanged',
+	bindI18nStore: '',
+	// nsMode: 'fallback' // loop through all namespaces given to hook, HOC, render prop for key lookup
+	transEmptyNodeValue: '',
+	transSupportBasicHtmlNodes: true,
+	transWrapTextNodes: '',
+	transKeepBasicHtmlNodesFor: ['br', 'strong', 'i', 'p'],
+	// hashTransKey: key => key // calculate a key for Trans component based on defaultValue
+	useSuspense: true,
+	unescape,
+	transDefaultProps: undefined, // { tOptions: {}, shouldUnescape: false, values: {}, components: [] }
+};
+
+export const setDefaults = (options = {}) => {
+	defaultOptions = { ...defaultOptions, ...options };
+};
+
+export const getDefaults = () => defaultOptions;

package/src/helpers.d.ts

@@ -0,0 +1,3 @@
+// Internal Helpers
+export type $Tuple<T> = readonly [T?, ...T[]];
+export type $Subtract<T extends K, K> = Omit<T, keyof K>;

package/src/i18nInstance.js

@@ -0,0 +1,7 @@
+let i18nInstance;
+
+export const setI18n = (instance) => {
+	i18nInstance = instance;
+};
+
+export const getI18n = () => i18nInstance;

package/src/index.d.ts

@@ -0,0 +1,315 @@
+import type { $Tuple } from './helpers.js';
+import type {
+	ReactOptions,
+	i18n,
+	Resource,
+	FlatNamespace,
+	Namespace,
+	TypeOptions,
+	TFunction,
+	KeyPrefix,
+	KeyPrefixSelector,
+	NsResource,
+	ParseKeys,
+	TOptions,
+} from 'i18next';
+import type { ComponentBody, Context, ElementDescriptor } from 'octane';
+import {
+	Trans,
+	TransProps,
+	TransSelectorProps,
+	ErrorCode,
+	ErrorArgs,
+} from './TransWithoutContext.js';
+export { initReactI18next } from './initReactI18next.js';
+
+export type OctaneNode = unknown;
+export type OctaneElement<P = any> = ElementDescriptor<P>;
+export type OctaneComponentType<P = any> = ComponentBody<P>;
+type ComponentProps<C> = C extends ComponentBody<infer P> ? P : never;
+
+export function nodesToString(
+	children: OctaneNode,
+	i18nOptions?: ReactOptions,
+	i18n?: i18n,
+	i18nKey?: string,
+): string;
+
+export const TransWithoutContext: typeof Trans;
+export { Trans, TransProps, TransSelectorProps, ErrorArgs, ErrorCode };
+
+/**
+ * Content declaration for IcuTrans component
+ * Describes React components as type + props blueprints that will be rendered
+ */
+export interface IcuTransContentDeclaration {
+	type: string | OctaneComponentType<any>;
+	props?: {
+		children?: IcuTransContentDeclaration | IcuTransContentDeclaration[];
+		[key: string]: any;
+	};
+}
+
+/**
+ * Props for IcuTransWithoutContext component (no React context)
+ */
+export type IcuTransWithoutContextProps<
+	Key extends ParseKeys<Ns, TOpt, KPrefix>,
+	Ns extends Namespace = _DefaultNamespace,
+	KPrefix = undefined,
+	TContext extends string | undefined = undefined,
+	TOpt extends TOptions & { context?: TContext } = { context: TContext },
+> = {
+	/** The i18n key to look up the translation */
+	i18nKey: Key;
+	/** The default translation in ICU format with numbered tags (e.g., "<0>Click here</0>") */
+	defaultTranslation: string;
+	/** Declaration tree describing React components and their props */
+	content: IcuTransContentDeclaration[];
+	/** Optional namespace(s) for the translation */
+	// 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);
+	/** Optional values for ICU variable interpolation */
+	values?: Record<string, any>;
+	/** i18next instance. If not provided, uses global instance */
+	i18n?: i18n;
+	/** Custom translation function */
+	t?: TFunction<Ns, KPrefix>;
+};
+
+/**
+ * Props for IcuTrans component (with React context support)
+ */
+export type IcuTransProps<
+	Key extends ParseKeys<Ns, TOpt, KPrefix>,
+	Ns extends Namespace = _DefaultNamespace,
+	KPrefix = undefined,
+	TContext extends string | undefined = undefined,
+	TOpt extends TOptions & { context?: TContext } = { context: TContext },
+> = IcuTransWithoutContextProps<Key, Ns, KPrefix, TContext, TOpt>;
+
+/**
+ * IcuTrans component for rendering ICU MessageFormat translations
+ * This is the context-aware version that works with I18nextProvider
+ *
+ * @example
+ * ```tsx
+ * // Type-safe usage with namespace
+ * <IcuTrans<'welcome.message', 'common'>
+ *   i18nKey="welcome.message"
+ *   defaultTranslation="Welcome <0>friend</0>!"
+ *   content={[{ type: 'strong', props: {} }]}
+ * />
+ * ```
+ */
+export interface IcuTransComponent {
+	<
+		Key extends ParseKeys<Ns, TOpt, KPrefix>,
+		Ns extends Namespace = _DefaultNamespace,
+		KPrefix = undefined,
+		TContext extends string | undefined = undefined,
+		TOpt extends TOptions & { context?: TContext } = { context: TContext },
+	>(
+		props: IcuTransProps<Key, Ns, KPrefix, TContext, TOpt>,
+	): OctaneNode;
+}
+
+/**
+ * IcuTransWithoutContext component for rendering ICU MessageFormat translations
+ * This version does not use React context and requires explicit i18n instance
+ *
+ * @example
+ * ```tsx
+ * // Type-safe usage with namespace
+ * <IcuTransWithoutContext<'welcome.message', 'common'>
+ *   i18nKey="welcome.message"
+ *   defaultTranslation="Welcome <0>back</0>!"
+ *   content={[{ type: 'strong', props: {} }]}
+ *   i18n={i18nInstance}
+ * />
+ * ```
+ */
+export interface IcuTransWithoutContextComponent {
+	<
+		Key extends ParseKeys<Ns, TOpt, KPrefix>,
+		Ns extends Namespace = _DefaultNamespace,
+		KPrefix = undefined,
+		TContext extends string | undefined = undefined,
+		TOpt extends TOptions & { context?: TContext } = { context: TContext },
+	>(
+		props: IcuTransWithoutContextProps<Key, Ns, KPrefix, TContext, TOpt>,
+	): OctaneNode;
+}
+
+export const IcuTrans: IcuTransComponent;
+export const IcuTransWithoutContext: IcuTransWithoutContextComponent;
+
+export function setDefaults(options: ReactOptions): void;
+export function getDefaults(): ReactOptions;
+export function setI18n(instance: i18n): void;
+export function getI18n(): i18n;
+export function composeInitialProps(ForComponent: any): (ctx: unknown) => Promise<any>;
+export function getInitialProps(): {
+	initialI18nStore: {
+		[ns: string]: {};
+	};
+	initialLanguage: string;
+};
+
+export interface ReportNamespaces {
+	addUsedNamespaces(namespaces: Namespace): void;
+	getUsedNamespaces(): string[];
+}
+
+declare module 'i18next' {
+	// interface i18n {
+	//   reportNamespaces?: ReportNamespaces;
+	// }
+	interface CustomInstanceExtensions {
+		reportNamespaces?: ReportNamespaces;
+	}
+}
+
+type _DefaultNamespace = TypeOptions['defaultNS'];
+
+export function useSSR(initialI18nStore: Resource, initialLanguage: string): void;
+
+// If the version is earlier than i18next v25.4.0, enableSelector does not exist in TypeOptions, so a conditional type is used to maintain type compatibility.
+type _EnableSelector = TypeOptions extends { enableSelector: infer U } ? U : false;
+
+export type UseTranslationOptions<KPrefix> = {
+	i18n?: i18n;
+	useSuspense?: boolean;
+	keyPrefix?: KPrefix;
+	bindI18n?: string | false;
+	nsMode?: 'fallback' | 'default';
+	lng?: string;
+	// other of these options might also work: https://github.com/i18next/i18next/blob/master/index.d.ts#L127
+};
+
+export type UseTranslationResponse<Ns extends Namespace, KPrefix> = [
+	t: TFunction<Ns, KPrefix>,
+	i18n: i18n,
+	ready: boolean,
+] & {
+	t: TFunction<Ns, KPrefix>;
+	i18n: i18n;
+	ready: boolean;
+};
+
+// Workaround to make code completion to work when suggesting namespaces.
+// This is a typescript limitation when using generics with default values,
+// it'll be addressed in this issue: https://github.com/microsoft/TypeScript/issues/52516
+export type FallbackNs<Ns> = Ns extends undefined
+	? _DefaultNamespace
+	: Ns extends Namespace
+		? Ns
+		: _DefaultNamespace;
+
+export const useTranslation: _EnableSelector extends true | 'optimize'
+	? UseTranslationSelector
+	: UseTranslationLegacy;
+
+interface UseTranslationLegacy {
+	<
+		const Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
+		const KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined,
+	>(
+		ns?: Ns,
+		options?: UseTranslationOptions<KPrefix>,
+	): UseTranslationResponse<FallbackNs<Ns>, KPrefix>;
+}
+
+interface UseTranslationSelector {
+	// Overload: selector function as keyPrefix — provides type-safe key narrowing
+	<
+		const Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined,
+		const KPrefix extends KeyPrefixSelector<FallbackNs<Ns>>,
+	>(
+		ns: Ns,
+		options: UseTranslationOptions<KPrefix> & { keyPrefix: KPrefix },
+	): UseTranslationResponse<FallbackNs<Ns>, KPrefix>;
+
+	// Overload: string or undefined keyPrefix (original behavior)
+	<
+		const Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
+		const KPrefix = undefined,
+	>(
+		ns?: Ns,
+		options?: UseTranslationOptions<KPrefix>,
+	): UseTranslationResponse<FallbackNs<Ns>, KPrefix>;
+}
+
+// Need to see usage to improve this
+export function withSSR(): <Props>(
+	WrappedComponent: OctaneComponentType<Props>,
+) => OctaneComponentType<
+	Props & {
+		initialI18nStore: Resource;
+		initialLanguage: string;
+	}
+> & {
+	getInitialProps: (ctx: unknown) => Promise<any>;
+};
+
+export interface WithTranslation<
+	Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
+	KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined,
+> {
+	t: TFunction<FallbackNs<Ns>, KPrefix>;
+	i18n: i18n;
+	tReady: boolean;
+}
+
+export interface WithTranslationProps {
+	i18n?: i18n;
+	useSuspense?: boolean;
+}
+
+export function withTranslation<
+	Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
+	KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined,
+>(
+	ns?: Ns,
+	options?: {
+		withRef?: boolean;
+		keyPrefix?: KPrefix;
+	},
+): <C extends OctaneComponentType<any>, ResolvedProps = ComponentProps<C>>(
+	component: C,
+) => OctaneComponentType<
+	Omit<ResolvedProps, keyof WithTranslation<Ns>> & WithTranslationProps & { ref?: unknown }
+>;
+
+export interface I18nextProviderProps {
+	children?: OctaneNode;
+	i18n: i18n;
+	defaultNS?: string | string[];
+}
+
+export const I18nextProvider: OctaneComponentType<I18nextProviderProps>;
+export const I18nContext: Context<{ i18n: i18n; defaultNS?: string | string[] }>;
+
+export interface TranslationProps<
+	Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
+	KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined,
+> {
+	children: (
+		t: TFunction<FallbackNs<Ns>, KPrefix>,
+		options: {
+			i18n: i18n;
+			lng: string;
+		},
+		ready: boolean,
+	) => OctaneNode;
+	ns?: Ns;
+	i18n?: i18n;
+	useSuspense?: boolean;
+	keyPrefix?: KPrefix;
+	nsMode?: 'fallback' | 'default';
+}
+
+export function Translation<
+	Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
+	KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined,
+>(props: TranslationProps<Ns, KPrefix>): any;

package/src/index.js

@@ -0,0 +1,26 @@
+export { Trans } from './Trans.js';
+export { Trans as TransWithoutContext } from './TransWithoutContext.js';
+export { IcuTrans } from './IcuTrans.js';
+export { IcuTransWithoutContext } from './IcuTransWithoutContext.js';
+export { useTranslation } from './useTranslation.js';
+export { withTranslation } from './withTranslation.js';
+export { Translation } from './Translation.js';
+export { I18nextProvider } from './I18nextProvider.js';
+export { withSSR } from './withSSR.js';
+export { useSSR } from './useSSR.js';
+export { initReactI18next } from './initReactI18next.js';
+export { setDefaults, getDefaults } from './defaults.js';
+export { setI18n, getI18n } from './i18nInstance.js';
+
+export { nodesToString } from './Trans.js';
+
+export { I18nContext, composeInitialProps, getInitialProps } from './context.js';
+
+// dummy functions for icu.macro support
+
+export const date = () => '';
+export const time = () => '';
+export const number = () => '';
+export const select = () => '';
+export const plural = () => '';
+export const selectOrdinal = () => '';

package/src/initReactI18next.d.ts

@@ -0,0 +1,3 @@
+import type { ThirdPartyModule } from 'i18next';
+
+export const initReactI18next: ThirdPartyModule;

package/src/initReactI18next.js

@@ -0,0 +1,11 @@
+import { setDefaults } from './defaults.js';
+import { setI18n } from './i18nInstance.js';
+
+export const initReactI18next = {
+	type: '3rdParty',
+
+	init(instance) {
+		setDefaults(instance.options.react);
+		setI18n(instance);
+	},
+};

package/src/internal.js

@@ -0,0 +1,42 @@
+// Slot mechanics for @octanejs/i18next's published plain-JS hook layer.
+// Compiled callers pass a call-site Symbol as the trailing argument; each
+// composed base hook gets a deterministic sub-slot. Tag-only symbols cover
+// renderHook and other slotless callers while remaining distinct inside the
+// runtime's ambient withSlot path.
+const subSlotCache = new Map();
+const bareTagCache = new Map();
+
+export function subSlot(slot, tag) {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) bareTagCache.set(tag, (bare = Symbol.for(`:${tag}`)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let symbol = byTag.get(tag);
+	if (symbol === undefined) {
+		symbol = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		byTag.set(tag, symbol);
+	}
+	return symbol;
+}
+
+export function splitSlot(args) {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}
+
+const componentSlots = new Map();
+
+// A fixed symbol is safe for a plain-JS component because every component
+// instance owns an independent hook scope.
+export function S(tag) {
+	let symbol = componentSlots.get(tag);
+	if (symbol === undefined) {
+		symbol = Symbol.for(`@octanejs/i18next:${tag}`);
+		componentSlots.set(tag, symbol);
+	}
+	return symbol;
+}

package/src/unescape.js

@@ -0,0 +1,31 @@
+// unescape common html entities
+
+const matchHtmlEntity =
+	/&(?:amp|#38|lt|#60|gt|#62|apos|#39|quot|#34|nbsp|#160|copy|#169|reg|#174|hellip|#8230|#x2F|#47);/g;
+
+const htmlEntities = {
+	'&': '&',
+	'&': '&',
+	'&lt;': '<',
+	'&#60;': '<',
+	'&gt;': '>',
+	'&#62;': '>',
+	'&apos;': "'",
+	'&#39;': "'",
+	'&quot;': '"',
+	'&#34;': '"',
+	'&nbsp;': ' ',
+	'&#160;': ' ',
+	'&copy;': '©',
+	'&#169;': '©',
+	'&reg;': '®',
+	'&#174;': '®',
+	'&hellip;': '…',
+	'&#8230;': '…',
+	'&#x2F;': '/',
+	'&#47;': '/',
+};
+
+const unescapeHtmlEntity = (m) => htmlEntities[m];
+
+export const unescape = (text) => text.replace(matchHtmlEntity, unescapeHtmlEntity);

package/src/useSSR.js

@@ -0,0 +1,55 @@
+// Ported from react-i18next@17.0.9 (8b4a9ea): context lookup -> octane.
+import { useContext } from 'octane';
+import { getI18n, I18nContext } from './context.js';
+import { warnOnce } from './utils.js';
+import { splitSlot } from './internal.js';
+
+export const useSSR = (initialI18nStore, initialLanguage, ...rest) => {
+	const [user] = splitSlot(rest);
+	const props = user[0] || {};
+	const { i18n: i18nFromProps } = props;
+	const { i18n: i18nFromContext } = useContext(I18nContext) || {};
+	const i18n = i18nFromProps || i18nFromContext || getI18n();
+
+	if (!i18n) {
+		warnOnce(
+			i18n,
+			'NO_I18NEXT_INSTANCE',
+			'useSSR: You will need to pass in an i18next instance by using initReactI18next or by passing it via props or context. In monorepo setups, make sure there is only one instance of react-i18next.',
+		);
+		return;
+	}
+
+	// opt out if is a cloned instance, eg. created by i18next-http-middleware on request
+	// -> do not set initial stuff on server side
+	if (i18n.options?.isClone) return;
+
+	// nextjs / SSR: getting data from next.js or other ssr stack
+	if (initialI18nStore && !i18n.initializedStoreOnce) {
+		if (!i18n.services?.resourceStore) {
+			warnOnce(
+				i18n,
+				'I18N_NOT_INITIALIZED',
+				'useSSR: i18n instance was found but not initialized (services.resourceStore is missing). Make sure you call i18next.init() before using useSSR — e.g. at module level, not only in getStaticProps/getServerSideProps.',
+			);
+			return;
+		}
+		i18n.services.resourceStore.data = initialI18nStore;
+
+		// add namespaces to the config - so a languageChange call loads all namespaces needed
+		i18n.options.ns = Object.values(initialI18nStore).reduce((mem, lngResources) => {
+			Object.keys(lngResources).forEach((ns) => {
+				if (mem.indexOf(ns) < 0) mem.push(ns);
+			});
+			return mem;
+		}, i18n.options.ns);
+
+		i18n.initializedStoreOnce = true;
+		i18n.isInitialized = true;
+	}
+
+	if (initialLanguage && !i18n.initializedLanguageOnce) {
+		i18n.changeLanguage(initialLanguage);
+		i18n.initializedLanguageOnce = true;
+	}
+};