How to translate <title> with i18next?

[edwin-speer]

Fixed, see fix below.

I'm using i18next to translate texts. But I'm unable to translate the page title (title meta tag/document.title).

When I do this (when following the documentation):

export const Route = createFileRoute("/about")({
  component: About,
  head: () => ({
    meta: [
      {
        title: i18n.t("title.about", "About"),
      },
    ],
  }),
});

The text is not translated, probably because the translation file is not yet loaded when head() is called.

The <RouterProvider/> is wrapped inside <I18nextProvider/>.

It seems the problem is that head() is only called once and not again when the translation file is loaded.

I now "solved" it in a very hacky (and possibly brittle) way, like this

    meta: [
      {
        title: i18n.t("title.about", "About"),
        translationKey: "title.about"
      },
    ],

Later I read out the translationKey and set document.title, but it's very non standard and not a desired solution.

I couldn't find any documentation on how to solve this, although this problem seems to be not uncommon.

Is this a bug, feature request or am I missing something?

I'm using
@tanstack/router-plugin 1.111.3

[edwin-speer]

For anyone with the same problem: I fixed it with a hook:

usePageTitle.ts

import { useRouter } from "@tanstack/react-router";
import { useEffect } from "react";
import { useTranslation } from "react-i18next";

export const usePageTitle = () => {
	const { t } = useTranslation();
	const router = useRouter();

	useEffect(() => {
		void router?.invalidate();
	}, [router, t]);
};

And then include it in your topmost component.

usePageTitle();

[codinginflow]

Thank you. Would you call this once in the __root.tsx? Or on each page individually?

[edwin-speer]

Only once

[codinginflow]

This seems to cause beforeLoad to run twice on page load. Do you think @dbgordon09's solution might be better?

[dbgordon09]

@edwin-speer You sir are a gentleman and a scholar 🎩 This helped me resolve the issue with translating meta on my side.

Turns out the configuration of

{
    defaultNS: false,
    ns: [],
}

to remove namespaces was causing i18n.t() to not work correctly. Removing that add using the following hook in __root.tsx works!

/**
 * A hook that manages language change effects in the application.
 * It tracks the current i18n locale and updates the document's text direction
 * when the language changes. The hook also forces a component rerender by
 * updating state and triggers a router invalidation to ensure the application
 * updates accordingly.
 *
 * The hook uses a state setter to trigger rerenders and sets up an i18n
 * languageChanged event listener to handle language changes. It cleans up
 * the event listener when the component unmounts.
 *
 */
export function useLanguageChange() {
  const [, setLocale] = useState(i18n.language);
  const router = useRouter();

  useEffect(() => {
    const handler = (locale: string) => {
      setLocale(locale);
      document.documentElement.dir = i18n.dir(locale);
      void router?.invalidate();
    };
    i18n.on("languageChanged", handler);
    return () => i18n.off("languageChanged", handler);
  }, []);
}

[codinginflow]

This solution is better because it doesn't trigger beforeLoad twice on page load

[edwin-speer]

Three improvements for this code:

1. Next to dir, lang should also be updated.
2. dir and lang should also be set when loading the page, not only when the language is changed.
3. useEffect wants the router dependency. This doesn't trigger useEffect unnecessarily.

Updated code

function setDocumentLocale(locale: string) {
	document.documentElement.dir = i18nConfig.dir(locale);
	document.documentElement.lang = locale;
}

export const usePageTitle = () => {
	const [locale, setLocale] = useState(i18nConfig.language);
	const router = useRouter();

	setDocumentLocale(locale);

	useEffect(() => {
		const handler = (locale: string) => {
			setLocale(locale);
			setDocumentLocale(locale);
			void router?.invalidate();
		};
		i18nConfig.on("languageChanged", handler);
		return () => {
			i18nConfig.off("languageChanged", handler);
		};
	}, [router]);
};

[UdaraWanasinghe]

You can pass i18n with the router context

// __root.tsx
export const Route = createRootRouteWithContext<{
  i18n: typeof i18next;
}>()({
  head: ({ match: { context: { i18n }} }) => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        name: "viewport",
        content: "width=device-width, initial-scale=1",
      },
      {
        title: i18n.t("title") || undefined,
      },
    ],
  }),
  shellComponent: RootDocument,
});

// router.tsx
import { createRouter } from "@tanstack/react-router";
import i18next from "i18next";
import { I18nextProvider } from "react-i18next";

import { createI18nInstance } from "./i18n";
import { routeTree } from "./routeTree.gen";

interface RouterContext {
  i18n: typeof i18next;
}

export const getRouter = async () => {
  const i18n = await createI18nInstance({
    ...yourOptionsHere
  });
  const routerContext: RouterContext = {
    i18n,
  };
  const router = createRouter({
      routeTree,
      defaultPreload: "intent",
      context: routerContext,
      scrollRestoration: true,
      Wrap: ({ children }) => (
        <I18nextProvider i18n={i18n}>
          {children}
        </I18nextProvider>
      ),
    });
    return router;
}

// i18n.ts
import { createIsomorphicFn } from "@tanstack/react-start";
import { getCookie, setCookie } from "@tanstack/react-start/server";
import Cookies from "js-cookie";
import type { LanguageDetectorModule } from "i18next";
import i18n, { createInstance, InitOptions } from "i18next";
import { initReactI18next } from "react-i18next";

type CookieOptions = {
  domain?: string;
  path?: string;
  sameSite?: "lax" | "strict" | "none";
  secure?: boolean;
  expires?: Date;
};

type TanstackLanguageDetectorOptions = {
  cookieName: string;
  cookieOptions?: CookieOptions;
};

function TanstackLanguageDetector(): LanguageDetectorModule {
  let options: TanstackLanguageDetectorOptions = {
    cookieName: "locale",
  };
  return {
    type: "languageDetector",
    init(_services, detectorOptions: TanstackLanguageDetectorOptions) {
      options = detectorOptions;
    },
    detect() {
      const language = getLanguageCookie({
        cookieName: options.cookieName,
      });
      return language;
    },
    cacheUserLanguage(lng: string) {
      setLanguageCookie({
        language: lng,
        cookieName: options.cookieName,
        cookieOptions: options.cookieOptions,
      });
    },
  };
}

type CreateI18nInstanceOptions = InitOptions & {
  detection?: TanstackLanguageDetectorOptions;
};

export async function createI18nInstance(options?: CreateI18nInstanceOptions) {
  const instance = getInstance();
  await instance
    .use(TanstackLanguageDetector())
    .use(initReactI18next)
    .init({
      resources,
      fallbackLng: "en",
      defaultNS: "translations",
      detection: {
        cookieName: "locale",
      },
      interpolation: {
        escapeValue: false, // not needed for react
      },
      ...options,
    });
  return instance;
}

// Isomorphic helpers to get i18n instance
type GetLanguageArgs = {
  cookieName: string;
};

const getInstance = createIsomorphicFn()
  .server(() => createInstance())
  .client(() => i18n);

// Helper functions to get and set language cookie
const getLanguageCookie = createIsomorphicFn()
  .server((args: GetLanguageArgs) => getCookie(args.cookieName))
  .client((args: GetLanguageArgs) => Cookies.get(args.cookieName));

type SetLanguageArgs = {
  language: string;
  cookieName: string;
  cookieOptions?: CookieOptions;
};

const setLanguageCookie = createIsomorphicFn()
  .server(({ language, cookieName, cookieOptions }: SetLanguageArgs) => {
    setCookie(cookieName, language, cookieOptions);
  })
  .client(({ language, cookieName, cookieOptions }: SetLanguageArgs) => {
    Cookies.set(cookieName, language, cookieOptions);
  });