Update README to sync with example repo and to stop using deprecated hooks

Author: sergiodxa

README.md

@@ -40,24 +40,44 @@ npm install i18next-fetch-backend
 First let's create some translation files in `app/locales`:
 
 ```ts
-// app/locales/en.ts
+// app/locales/en/translation.ts
 export default {
   title: "remix-i18next (en)",
-  description: "A Remix + Vite + remix-i18next example",
+  description: "A React Router + remix-i18next example",
 };
+
+// app/locales/en/index.ts
+import type { ResourceLanguage } from "i18next";
+import translation from "./translation"; // import your namespaced locales
+
+export default { translation } satisfies ResourceLanguage;
 ```
 
 ```ts
-// app/locales/es.ts
-import type en from "./en";
-
+// app/locales/en/translation.ts
 export default {
   title: "remix-i18next (es)",
-  description: "Un ejemplo de Remix + Vite + remix-i18next",
-} satisfies typeof en;
+  description: "Un ejemplo de React Router + remix-i18next",
+} satisfies typeof import("~/locales/en/translation").default;
+
+// app/locales/es/index.ts
+import type { ResourceLanguage } from "i18next";
+import translation from "./translation"; // import your namespaced locales
+
+export default { translation } satisfies ResourceLanguage;
 ```
 
-The type import and the `satisfies` are optional, but it will help us ensure that if we add or remove a key from the `en` locale (our default one) we will get a type error in the `es` locale so we can keep them in sync.
+The `satisfies typeof import("~/locales/en/translation").default` is optional, but it will help to ensure that if we add or remove a key from the `en` locale (the default one) we will get a type error in the `es` locale so we can keep them in sync.
+
+Then re-export them all the locales in `app/locales/index.ts`:
+
+```ts
+import type { Resource } from "i18next";
+import en from "./en";
+import es from "./es";
+
+export default { en, es } satisfies Resource;
+```
 
 ### Setup the Middleware
 
@@ -71,21 +91,38 @@ Create a file named `app/middleware/i18next.ts` with the following code:
 > Check older versions of the README for a guide on how to use RemixI18next class instead if you are using an older version of React Router or don't want to use the middleware.
 
 ```ts
+import { initReactI18next } from "react-i18next";
+import { createCookie } from "react-router";
 import { createI18nextMiddleware } from "remix-i18next/middleware";
-import en from "~/locales/en";
-import es from "~/locales/es";
+import resources from "~/locales"; // Import your locales
+import "i18next";
+
+// This cookie will be used to store the user locale preference
+export const localeCookie = createCookie("lng", {
+  path: "/",
+  sameSite: "lax",
+  secure: process.env.NODE_ENV === "production",
+  httpOnly: true,
+});
 
 export const [i18nextMiddleware, getLocale, getInstance] =
   createI18nextMiddleware({
     detection: {
-      supportedLanguages: ["en", "es"],
-      fallbackLanguage: "en",
-    },
-    i18next: {
-      resources: { en: { translation: en }, es: { translation: es } },
-      // Other i18next options are available here
+      supportedLanguages: ["es", "en"], // Your supported languages, the fallback should be last
+      fallbackLanguage: "en", // Your fallback language
+      cookie: localeCookie, // The cookie to store the user preference
     },
+    i18next: { resources }, // Your locales
+    plugins: [initReactI18next], // Plugins you may need, like react-i18next
   });
+
+// This adds type-safety to the `t` function
+declare module "i18next" {
+  interface CustomTypeOptions {
+    defaultNS: "translation";
+    resources: typeof resources.en; // Use `en` as source of truth for the types
+  }
+}
 ```
 
 Then in your `app/root.tsx` setup the middleware:
@@ -151,7 +188,7 @@ This will return a new `TFunction` instance with the locale set to `es`.
 
 ### Usage with react-i18next
 
-So far this has configured the i18next instance to inside React Router loaders and actions, but in many cases we will need to use it directly in our React components.
+So far this has configured the i18next instance to use inside React Router loaders and actions, but in many cases we will need to use it directly in our React components.
 
 To do this, we need to setup react-i18next.
 
@@ -160,7 +197,7 @@ Let's start by updating the `entry.client.tsx` and `entry.server.tsx` files to u
 > [!TIP]
 > If you don't have these files, run `npx react-router reveal` to generate them. They are hidden by default.
 
-### Update the root route
+#### Update the root route
 
 First of all, we want to send the locale detected server-side by the middleware to the UI. To do this, we will return the locale from the `app/root.tsx` route.
 
@@ -173,7 +210,7 @@ import {
   Scripts,
   ScrollRestoration,
 } from "react-router";
-import { useChangeLanguage } from "remix-i18next/react";
+import { useEffect } from "react";
 import type { Route } from "./+types/root";
 import {
   getLocale,
@@ -187,8 +224,8 @@ export const middleware = [i18nextMiddleware];
 export async function loader({ context }: Route.LoaderArgs) {
   let locale = getLocale(context);
   return data(
-    { locale },
-    { headers: { "Set-Cookie": await localeCookie.serialize(locale) } }
+    { locale }, // Return the locale to the UI
+    { headers: { "Set-Cookie": await localeCookie.serialize(locale) } },
   );
 }
 
@@ -212,17 +249,20 @@ export function Layout({ children }: { children: React.ReactNode }) {
   );
 }
 
-export default function App({ loaderData }: Route.ComponentProps) {
-  useChangeLanguage(loaderData.locale);
+export default function App({ loaderData: { locale } }: Route.ComponentProps) {
+  let { i18n } = useTranslation();
+  useEffect(() => {
+    if (i18n.language !== locale) i18n.changeLanguage(locale);
+  }, [locale, i18n]);
   return <Outlet />;
 }
 ```
 
 We made a few changes here:
 
-1. We added a `loader` that gets the locale from the context (set by the middleware) and returns it to the UI.
+1. We added a `loader` that gets the locale from the context (set by the middleware) and returns it to the UI. It also saves the locale in a cookie so it can be read from there in future requests.
 2. In the root Layout component, we use the `useTranslation` hook to get the i18n instance and set the `lang` attribute of the `<html>` tag, along the `dir` attribute.
-3. We added the `useChangeLanguage` hook to set the language in the i18next instance, this will keep the language in sync with the locale detected by the middleware after a refresh of the loader data.
+3. We added a `useEffect` in the `App` component to change the language of the i18n instance when the locale changes. This keeps the i18n instance in sync with the locale detected server-side.
 
 #### Client-side configuration
 
@@ -243,8 +283,11 @@ async function main() {
     .use(Fetch)
     .use(I18nextBrowserLanguageDetector)
     .init({
-      fallbackLng: "en",
+      fallbackLng: "en", // Change this to your default language
+      // Here we only want to detect the language from the html tag
+      // since the middleware already detected the language server-side
       detection: { order: ["htmlTag"], caches: [] },
+      // Update this to the path where your locales will be served
       backend: { loadPath: "/api/locales/{{lng}}/{{ns}}" },
     });
 
@@ -255,7 +298,7 @@ async function main() {
         <StrictMode>
           <HydratedRouter />
         </StrictMode>
-      </I18nextProvider>
+      </I18nextProvider>,
     );
   });
 }
@@ -265,7 +308,7 @@ main().catch((error) => console.error(error));
 
 We're configuring `i18next-browser-languagedetector` to detect the language based on the `lang` attribute of the `<html>` tag. This way, we can use the same language detected by the middleware server-side.
 
-### API for locales
+#### API for locales
 
 The `app/entry.client.tsx` has the i18next backend configured to load the locales from the path `/api/locales/{{lng}}/{{ns}}`. Feel free to customize this but for this guide we will use that path.
 
@@ -275,32 +318,20 @@ Now we need to create a route to serve the locales. So let's create a file `app/
 import { data } from "react-router";
 import { cacheHeader } from "pretty-cache-header";
 import { z } from "zod";
-import enTranslation from "~/locales/en";
-import esTranslation from "~/locales/es";
+import resources from "~/locales";
 import type { Route } from "./+types/locales";
 
-const resources = {
-  en: { translation: enTranslation },
-  es: { translation: esTranslation },
-};
-
 export async function loader({ params }: Route.LoaderArgs) {
   const lng = z
-    .string()
-    .refine((lng): lng is keyof typeof resources =>
-      Object.keys(resources).includes(lng)
-    )
+    .enum(Object.keys(resources) as Array<keyof typeof resources>)
     .safeParse(params.lng);
 
   if (lng.error) return data({ error: lng.error }, { status: 400 });
 
   const namespaces = resources[lng.data];
 
   const ns = z
-    .string()
-    .refine((ns): ns is keyof typeof namespaces => {
-      return Object.keys(resources[lng.data]).includes(ns);
-    })
+    .enum(Object.keys(namespaces) as Array<keyof typeof namespaces>)
     .safeParse(params.ns);
 
   if (ns.error) return data({ error: ns.error }, { status: 400 });
@@ -318,7 +349,7 @@ export async function loader({ params }: Route.LoaderArgs) {
         staleWhileRevalidate: "7d",
         // Serve stale content if there's an error for 7 days
         staleIfError: "7d",
-      })
+      }),
     );
   }
 
@@ -335,17 +366,13 @@ They are not hard requirements, but they are useful for our example, feel free t
 
 Finally, ensure the route is configured in your `app/routes.ts` file. You can set the path to `/api/locales/:lng/:ns` so it matches the path used in the `entry.client.tsx` file, if you use something else remember to update the `loadPath` in the i18next configuration.
 
-### Server-side configuration
+#### Server-side configuration
 
 Now in your `entry.server.tsx` replace the default code with this:
 
 ```tsx
 import { PassThrough } from "node:stream";
-
-import type {
-  EntryContext,
-  RouterContextProvider,
-} from "react-router";
+import type { EntryContext, RouterContextProvider } from "react-router";
 import { createReadableStreamFromReadable } from "@react-router/node";
 import { ServerRouter } from "react-router";
 import { isbot } from "isbot";
@@ -361,7 +388,7 @@ export default function handleRequest(
   responseStatusCode: number,
   responseHeaders: Headers,
   entryContext: EntryContext,
-  routerContext: RouterContextProvider
+  routerContext: RouterContextProvider,
 ) {
   return new Promise((resolve, reject) => {
     let shellRendered = false;
@@ -388,7 +415,7 @@ export default function handleRequest(
             new Response(stream, {
               headers: responseHeaders,
               status: responseStatusCode,
-            })
+            }),
           );
 
           pipe(body);
@@ -400,7 +427,7 @@ export default function handleRequest(
           responseStatusCode = 500;
           if (shellRendered) console.error(error);
         },
-      }
+      },
     );
 
     setTimeout(abort, streamTimeout + 1000);
@@ -412,7 +439,9 @@ Here we are using the `getInstance` function from the middleware to get the i18n
 
 This way, we can re-use the instance created in the middleware and avoid creating a new one. And since the instance is already configured with the language we detected, we can use it directly in the `I18nextProvider`.
 
-## Finding the locale from the request URL pathname
+## Common Scenarios
+
+### Finding the locale from the request URL pathname
 
 If you want to keep the user locale on the pathname, you have two possible options.
 
@@ -441,7 +470,7 @@ export const [i18nextMiddleware, getLocale, getInstance] =
 
 The locale returned by `findLocale` will be validated against the list of supported locales, in case it's not valid the fallback locale will be used.
 
-## Querying the locale from the database
+### Querying the locale from the database
 
 If your application stores the user locale in the database, you can use `findLocale` function to query the database and return the locale.
 
@@ -458,7 +487,7 @@ export let i18n = new RemixI18Next({
 });
 ```
 
-## Store the locale in a cookie
+### Store the locale in a cookie
 
 If you want to store the locale in a cookie, you can create a cookie using `createCookie` helper from React Router and pass the Cookie object to the middleware.
 
@@ -505,12 +534,12 @@ export async function loader({ context }: Route.LoaderArgs) {
   let locale = getLocale(context);
   return data(
     { locale },
-    { headers: { "Set-Cookie": await localeCookie.serialize(locale) } }
+    { headers: { "Set-Cookie": await localeCookie.serialize(locale) } },
   );
 }
 ```
 
-## Store the locale in the session
+### Store the locale in the session
 
 Similarly to the cookie, you can store the locale in the session. To do this, you can create a session using `createSessionStorage` helpers from React Router and pass the SessionStorage object to the middleware.
 
@@ -564,7 +593,37 @@ export async function loader({ request, context }: Route.LoaderArgs) {
 
   return data(
     { locale },
-    { headers: { "Set-Cookie": await sessionStorage.commitSession(session) } }
+    { headers: { "Set-Cookie": await sessionStorage.commitSession(session) } },
   );
 }
 ```
+
+### Handle Not Found Errors
+
+If you want to handle not found errors and show a custom internationalized 404 page, you can create a route with the path `*` and render your custom 404 page there.
+
+```tsx
+import { useTranslation } from "react-i18next";
+import { data, href, Link } from "react-router";
+
+export async function loader() {
+  return data(null, { status: 404 }); // Set the status to 404
+}
+
+export default function Component() {
+  let { t } = useTranslation("notFound");
+
+  return (
+    <div style={{ fontFamily: "system-ui, sans-serif", lineHeight: "1.8" }}>
+      <h1>{t("title")}</h1>
+      <p>{t("description")}</p>
+
+      <Link to={href("/")}>{t("backToHome")}</Link>
+    </div>
+  );
+}
+```
+
+If you're using `@react-router/fs-routes` package, you can create a file named `app/routes/$.tsx` and it will be used automatically. If you're configuring your routes manually, create a file `app/routes/not-found.tsx` and add `route("*", "./routes/not-found.tsx")` to your routes configuration.
+
+Without this route, any not found request will not run the middleware in root, causing `entry.server.tsx` to not have the i18next instance configured, resulting in an error.