Refactor i18n settings and improve language load handling

This update separates the creation of i18n settings into its own function (@kit/i18n) and enhances the handling of language and namespace loading in i18n.client. It tracks loaded languages and namespaces, and prevents rendering if none are loaded or after a maximum number of iterations. The usage of Suspense has also been modified in root-providers to employ a null fallback.

apps/web/components/root-providers.tsx

@@ -46,7 +46,7 @@ export function RootProviders({
   return (
     <QueryClientProvider client={queryClient}>
       <ReactQueryStreamedHydration>
-        <Suspense>
+        <Suspense fallback={null}>
           <I18nProvider settings={i18nSettings} resolver={i18nResolver}>
             <CaptchaProvider>
               <CaptchaTokenSetter siteKey={captchaSiteKey} />

apps/web/lib/i18n/i18n.settings.ts

@@ -1,4 +1,4 @@
-import { InitOptions } from 'i18next';
+import { createI18nSettings } from '@kit/i18n';
 
 /**
  * The default language of the application.
@@ -43,7 +43,7 @@ export const defaultI18nNamespaces = [
 export function getI18nSettings(
   language: string | undefined,
   ns: string | string[] = defaultI18nNamespaces,
-): InitOptions {
+) {
   let lng = language ?? defaultLanguage;
 
   if (!languages.includes(lng)) {
@@ -54,18 +54,9 @@ export function getI18nSettings(
     lng = defaultLanguage;
   }
 
-  return {
+  return createI18nSettings({
-    supportedLngs: languages,
+    language: lng,
-    fallbackLng: languages[0],
+    namespaces: ns,
-    detection: undefined,
+    languages,
-    lng,
+  });
-    load: 'languageOnly',
-    preload: false,
-    lowerCaseLng: true,
-    fallbackNS: defaultI18nNamespaces,
-    ns,
-    react: {
-      useSuspense: true,
-    },
-  };
 }

packages/i18n/package.json

@@ -10,6 +10,7 @@
   },
   "prettier": "@kit/prettier-config",
   "exports": {
+    ".": "./src/index.ts",
     "./server": "./src/i18n.server.ts",
     "./client": "./src/i18n.client.ts",
     "./provider": "./src/i18n-provider.tsx"

packages/i18n/src/create-i18n-settings.ts

@@ -0,0 +1,33 @@
+/**
+ * Get i18n settings for i18next.
+ * @param languages
+ * @param language
+ * @param namespaces
+ */
+export function createI18nSettings({
+  languages,
+  language,
+  namespaces,
+}: {
+  languages: string[];
+  language: string;
+  namespaces?: string | string[];
+}) {
+  const lng = language;
+  const ns = namespaces;
+
+  return {
+    supportedLngs: languages,
+    fallbackLng: languages[0],
+    detection: undefined,
+    lng,
+    load: 'languageOnly',
+    preload: false,
+    lowerCaseLng: true,
+    fallbackNS: ns,
+    ns,
+    react: {
+      useSuspense: true,
+    },
+  };
+}

packages/i18n/src/i18n-provider.tsx

@@ -1,7 +1,10 @@
 'use client';
 
-import { useSuspenseQuery } from '@tanstack/react-query';
+import type { InitOptions, i18n } from 'i18next';
-import type { InitOptions } from 'i18next';
+
+import { initializeI18nClient } from './i18n.client';
+
+let i18nInstance: i18n;
 
 type Resolver = (
   lang: string,
@@ -28,20 +31,17 @@ export function I18nProvider({
  * @param resolver
  */
 function useI18nClient(settings: InitOptions, resolver: Resolver) {
-  return useSuspenseQuery({
+  if (
-    queryKey: ['i18n', settings.lng],
+    !i18nInstance ||
-    queryFn: async () => {
+    i18nInstance.language !== settings.lng ||
-      const isBrowser = typeof window !== 'undefined';
+    i18nInstance.options.ns?.length !== settings.ns?.length
+  ) {
+    throw loadI18nInstance(settings, resolver);
+  }
 
-      if (isBrowser) {
+  return i18nInstance;
-        const { initializeI18nClient } = await import('./i18n.client');
+}
-
+
-        return await initializeI18nClient(settings, resolver);
+async function loadI18nInstance(settings: InitOptions, resolver: Resolver) {
-      } else {
+  i18nInstance = await initializeI18nClient(settings, resolver);
-        const { initializeServerI18n } = await import('./i18n.server');
-
-        return await initializeServerI18n(settings, resolver);
-      }
-    },
-  });
 }

packages/i18n/src/i18n.client.ts

@@ -3,6 +3,12 @@ import LanguageDetector from 'i18next-browser-languagedetector';
 import resourcesToBackend from 'i18next-resources-to-backend';
 import { initReactI18next } from 'react-i18next';
 
+// Keep track of the number of iterations
+let iteration = 0;
+
+// Maximum number of iterations
+const MAX_ITERATIONS = 20;
+
 /**
  * Initialize the i18n instance on the client.
  * @param settings - the i18n settings
@@ -12,11 +18,22 @@ export async function initializeI18nClient(
   settings: InitOptions,
   resolver: (lang: string, namespace: string) => Promise<object>,
 ): Promise<i18n> {
+  const loadedLanguages: string[] = [];
+  const loadedNamespaces: string[] = [];
+
   await i18next
     .use(
       resourcesToBackend(async (language, namespace, callback) => {
         const data = await resolver(language, namespace);
 
+        if (!loadedLanguages.includes(language)) {
+          loadedLanguages.push(language);
+        }
+
+        if (!loadedNamespaces.includes(namespace)) {
+          loadedNamespaces.push(namespace);
+        }
+
         return callback(null, data);
       }),
     )
@@ -41,5 +58,24 @@ export async function initializeI18nClient(
       },
     );
 
+  // to avoid infinite loops, we return the i18next instance after a certain number of iterations
+  // even if the languages and namespaces are not loaded
+  if (iteration >= MAX_ITERATIONS) {
+    console.debug(`Max iterations reached: ${MAX_ITERATIONS}`);
+
+    return i18next;
+  }
+
+  // keep component from rendering if no languages or namespaces are loaded
+  if (loadedLanguages.length === 0 || loadedNamespaces.length === 0) {
+    iteration++;
+
+    console.debug(
+      `Keeping component from rendering if no languages or namespaces are loaded. Iteration: ${iteration}. Will stop after ${MAX_ITERATIONS} iterations.`,
+    );
+
+    throw new Error('No languages or namespaces loaded');
+  }
+
   return i18next;
 }

packages/i18n/src/index.ts

@@ -0,0 +1 @@
+export * from './create-i18n-settings';