B2B-88: add starter kit structure and elements

packages/i18n/eslint.config.mjs

@@ -0,0 +1,3 @@
+import eslintConfigBase from '@kit/eslint-config/base.js';
+
+export default eslintConfigBase;

packages/i18n/node_modules/.bin/next

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules/next/dist/bin/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules/next/dist/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules/next/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules/next/dist/bin/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules/next/dist/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules/next/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../next/dist/bin/next" "$@"
+else
+  exec node  "$basedir/../next/dist/bin/next" "$@"
+fi

packages/i18n/node_modules/.bin/tsc

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsc" "$@"
+fi

packages/i18n/node_modules/.bin/tsserver

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/typescript@5.8.3/node_modules:/Users/devmcee/dev/mountbirch/MRB2B/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsserver" "$@"
+fi

packages/i18n/node_modules/@kit/eslint-config

@@ -0,0 +1 @@
+../../../../tooling/eslint

packages/i18n/node_modules/@kit/prettier-config

@@ -0,0 +1 @@
+../../../../tooling/prettier

packages/i18n/node_modules/@kit/shared

@@ -0,0 +1 @@
+../../../shared

packages/i18n/node_modules/@kit/tsconfig

@@ -0,0 +1 @@
+../../../../tooling/typescript

packages/i18n/node_modules/@tanstack/react-query

@@ -0,0 +1 @@
+../../../../node_modules/.pnpm/@tanstack+react-query@5.76.1_react@19.1.0/node_modules/@tanstack/react-query

packages/i18n/node_modules/i18next

@@ -0,0 +1 @@
+../../../node_modules/.pnpm/i18next@25.1.3_typescript@5.8.3/node_modules/i18next

packages/i18n/node_modules/i18next-browser-languagedetector

@@ -0,0 +1 @@
+../../../node_modules/.pnpm/i18next-browser-languagedetector@8.1.0/node_modules/i18next-browser-languagedetector

packages/i18n/node_modules/i18next-resources-to-backend

@@ -0,0 +1 @@
+../../../node_modules/.pnpm/i18next-resources-to-backend@1.2.1/node_modules/i18next-resources-to-backend

packages/i18n/node_modules/next

@@ -0,0 +1 @@
+../../../node_modules/.pnpm/next@15.3.2_@babel+core@7.27.4_@opentelemetry+api@1.9.0_babel-plugin-react-compiler@19.1.0-rc_krzs4il3c2axvegn27goximifi/node_modules/next

packages/i18n/node_modules/react

@@ -0,0 +1 @@
+../../../node_modules/.pnpm/react@19.1.0/node_modules/react

packages/i18n/node_modules/react-dom

@@ -0,0 +1 @@
+../../../node_modules/.pnpm/react-dom@19.1.0_react@19.1.0/node_modules/react-dom

packages/i18n/node_modules/react-i18next

@@ -0,0 +1 @@
+../../../node_modules/.pnpm/react-i18next@15.5.2_i18next@25.1.3_typescript@5.8.3__react-dom@19.1.0_react@19.1.0__react@19.1.0_typescript@5.8.3/node_modules/react-i18next

packages/i18n/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kit/i18n",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "clean": "git clean -xdf .turbo node_modules",
+    "format": "prettier --check \"**/*.{ts,tsx}\"",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "prettier": "@kit/prettier-config",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/i18n.server.ts",
+    "./client": "./src/i18n.client.ts",
+    "./provider": "./src/i18n-provider.tsx"
+  },
+  "devDependencies": {
+    "@kit/eslint-config": "workspace:*",
+    "@kit/prettier-config": "workspace:*",
+    "@kit/shared": "workspace:*",
+    "@kit/tsconfig": "workspace:*",
+    "@tanstack/react-query": "5.76.1",
+    "next": "15.3.2",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-i18next": "^15.5.1"
+  },
+  "dependencies": {
+    "i18next": "25.1.3",
+    "i18next-browser-languagedetector": "8.1.0",
+    "i18next-resources-to-backend": "^1.2.1"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,41 @@
+import type { InitOptions } from 'i18next';
+
+/**
+ * Get i18n settings for i18next.
+ * @param languages
+ * @param language
+ * @param namespaces
+ */
+export function createI18nSettings({
+  languages,
+  language,
+  namespaces,
+}: {
+  languages: string[];
+  language: string;
+  namespaces?: string | string[];
+}): InitOptions {
+  const lng = language;
+  const ns = namespaces;
+
+  return {
+    supportedLngs: languages,
+    fallbackLng: languages[0],
+    detection: undefined,
+    lng,
+    preload: false as const,
+    lowerCaseLng: true as const,
+    fallbackNS: ns,
+    missingInterpolationHandler: (text, value, options) => {
+      console.debug(
+        `Missing interpolation value for key: ${text}`,
+        value,
+        options,
+      );
+    },
+    ns,
+    react: {
+      useSuspense: true,
+    },
+  };
+}

packages/i18n/src/i18n-provider.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import type { InitOptions, i18n } from 'i18next';
+
+import { initializeI18nClient } from './i18n.client';
+
+let i18nInstance: i18n;
+
+type Resolver = (
+  lang: string,
+  namespace: string,
+) => Promise<Record<string, string>>;
+
+export function I18nProvider({
+  settings,
+  children,
+  resolver,
+}: React.PropsWithChildren<{
+  settings: InitOptions;
+  resolver: Resolver;
+}>) {
+  useI18nClient(settings, resolver);
+
+  return children;
+}
+
+/**
+ * @name useI18nClient
+ * @description A hook that initializes the i18n client.
+ * @param settings
+ * @param resolver
+ */
+function useI18nClient(settings: InitOptions, resolver: Resolver) {
+  if (
+    !i18nInstance ||
+    i18nInstance.language !== settings.lng ||
+    i18nInstance.options.ns?.length !== settings.ns?.length
+  ) {
+    throw loadI18nInstance(settings, resolver);
+  }
+
+  return i18nInstance;
+}
+
+async function loadI18nInstance(settings: InitOptions, resolver: Resolver) {
+  i18nInstance = await initializeI18nClient(settings, resolver);
+}

packages/i18n/src/i18n.client.ts

@@ -0,0 +1,81 @@
+import i18next, { type InitOptions, i18n } from 'i18next';
+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
+ * @param resolver - a function that resolves the i18n resources
+ */
+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);
+      }),
+    )
+    .use(LanguageDetector)
+    .use(initReactI18next)
+    .init(
+      {
+        ...settings,
+        detection: {
+          order: ['htmlTag', 'cookie', 'navigator'],
+          caches: ['cookie'],
+          lookupCookie: 'lang',
+        },
+        interpolation: {
+          escapeValue: false,
+        },
+      },
+      (err) => {
+        if (err) {
+          console.error('Error initializing i18n client', err);
+        }
+      },
+    );
+
+  // 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/i18n.server.ts

@@ -0,0 +1,151 @@
+import { type InitOptions, createInstance } from 'i18next';
+import resourcesToBackend from 'i18next-resources-to-backend';
+import { initReactI18next } from 'react-i18next/initReactI18next';
+
+/**
+ * Initialize the i18n instance on the server.
+ * This is useful for RSC and SSR.
+ * @param settings - the i18n settings
+ * @param resolver - a function that resolves the i18n resources
+ */
+export async function initializeServerI18n(
+  settings: InitOptions,
+  resolver: (language: string, namespace: string) => Promise<object>,
+) {
+  const i18nInstance = createInstance();
+  const loadedNamespaces = new Set<string>();
+
+  await new Promise((resolve) => {
+    void i18nInstance
+      .use(
+        resourcesToBackend(async (language, namespace, callback) => {
+          try {
+            const data = await resolver(language, namespace);
+            loadedNamespaces.add(namespace);
+
+            return callback(null, data);
+          } catch (error) {
+            console.log(
+              `Error loading i18n file: locales/${language}/${namespace}.json`,
+              error,
+            );
+
+            return callback(null, {});
+          }
+        }),
+      )
+      .use({
+        type: '3rdParty',
+        init: async (i18next: typeof i18nInstance) => {
+          let iterations = 0;
+          const maxIterations = 100;
+
+          // do not bind this to the i18next instance until it's initialized
+          while (i18next.isInitializing) {
+            iterations++;
+
+            if (iterations > maxIterations) {
+              console.error(
+                `i18next is not initialized after ${maxIterations} iterations`,
+              );
+
+              break;
+            }
+
+            await new Promise((resolve) => setTimeout(resolve, 1));
+          }
+
+          initReactI18next.init(i18next);
+          resolve(i18next);
+        },
+      })
+      .init(settings);
+  });
+
+  const namespaces = settings.ns as string[];
+
+  // If all namespaces are already loaded, return the i18n instance
+  if (loadedNamespaces.size === namespaces.length) {
+    return i18nInstance;
+  }
+
+  // Otherwise, wait for all namespaces to be loaded
+
+  const maxWaitTime = 0.1; // 100 milliseconds
+  const checkIntervalMs = 5; // 5 milliseconds
+
+  async function waitForNamespaces() {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < maxWaitTime) {
+      const allNamespacesLoaded = namespaces.every((ns) =>
+        loadedNamespaces.has(ns),
+      );
+
+      if (allNamespacesLoaded) {
+        return true;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, checkIntervalMs));
+    }
+
+    return false;
+  }
+
+  const success = await waitForNamespaces();
+
+  if (!success) {
+    console.warn(
+      `Not all namespaces were loaded after ${maxWaitTime}ms. Initialization may be incomplete.`,
+    );
+  }
+
+  return i18nInstance;
+}
+
+/**
+ * Parse the accept-language header value and return the languages that are included in the accepted languages.
+ * @param languageHeaderValue
+ * @param acceptedLanguages
+ */
+export function parseAcceptLanguageHeader(
+  languageHeaderValue: string | null | undefined,
+  acceptedLanguages: string[],
+): string[] {
+  // Return an empty array if the header value is not provided
+  if (!languageHeaderValue) return [];
+
+  const ignoreWildcard = true;
+
+  // Split the header value by comma and map each language to its quality value
+  return languageHeaderValue
+    .split(',')
+    .map((lang): [number, string] => {
+      const [locale, q = 'q=1'] = lang.split(';');
+
+      if (!locale) return [0, ''];
+
+      const trimmedLocale = locale.trim();
+      const numQ = Number(q.replace(/q ?=/, ''));
+
+      return [isNaN(numQ) ? 0 : numQ, trimmedLocale];
+    })
+    .sort(([q1], [q2]) => q2 - q1) // Sort by quality value in descending order
+    .flatMap(([_, locale]) => {
+      // Ignore wildcard '*' if 'ignoreWildcard' is true
+      if (locale === '*' && ignoreWildcard) return [];
+
+      const languageSegment = locale.split('-')[0];
+
+      if (!languageSegment) return [];
+
+      // Return the locale if it's included in the accepted languages
+      try {
+        return acceptedLanguages.includes(languageSegment)
+          ? [languageSegment]
+          : [];
+      } catch {
+        return [];
+      }
+    });
+}

packages/i18n/src/index.ts

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

packages/i18n/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@kit/tsconfig/base.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
+  },
+  "include": ["*.ts", "src"],
+  "exclude": ["node_modules"]
+}