remix-i18next

翻译您的 React Router 框架模式应用的最简单方法。

[!IMPORTANT] 如果您仍然在使用 Remix v2，请继续使用 remix-i18next v6，因为 v7 仅与 React Router v7 兼容。

为什么选择 remix-i18next？

易于设置，易于使用：只需几个步骤即可完成设置，并且配置简单。
没有其他要求：remix-i18next简化了您的 React Router 应用的国际化，无需额外的依赖项。
生产就绪：remix-i18next支持从加载器将翻译和配置选项传递到路由。
掌控一切：remix-i18next不会隐藏配置，因此您可以添加任何您想要的插件或随意配置。

设置

[!TIP] 如果您正在将 Remix 与 Vite 一起使用，请查看 https://github.com/sergiodxa/remix-vite-i18next 获取示例应用程序，如果您遇到问题，请将您的设置与示例进行比较。

安装

第一步是在您的项目中使用以下命令进行安装

npm install remix-i18next i18next react-i18next i18next-browser-languagedetector

您需要配置一个 i18next 后端和语言检测器，在这种情况下，您也可以安装它们，对于其余的设置指南，我们将使用 http 和 fs 后端。

npm install i18next-http-backend i18next-fs-backend

配置

首先让我们创建一些翻译文件

public/locales/en/common.json:

{
  "greeting": "Hello"
}

public/locales/es/common.json:

{
  "greeting": "Hola"
}

接下来，设置您的i18next 配置。

这两个文件可以放在您的应用程序文件夹中的任何位置。

对于此示例，我们将创建 app/i18n.ts

export default {
  // This is the list of languages your application supports
  supportedLngs: ["en", "es"],
  // This is the language you want to use in case
  // if the user language is not in the supportedLngs
  fallbackLng: "en",
  // The default namespace of i18next is "translation", but you can customize it here
  defaultNS: "common",
};

然后创建一个名为 i18next.server.ts 的文件，其中包含以下代码

import Backend from "i18next-fs-backend";
import { resolve } from "node:path";
import { RemixI18Next } from "remix-i18next/server";
import i18n from "~/i18n"; // your i18n configuration file

let i18next = new RemixI18Next({
  detection: {
    supportedLanguages: i18n.supportedLngs,
    fallbackLanguage: i18n.fallbackLng,
  },
  // This is the configuration for i18next used
  // when translating messages server-side only
  i18next: {
    ...i18n,
    backend: {
      loadPath: resolve("./public/locales/{{lng}}/{{ns}}.json"),
    },
  },
  // The i18next plugins you want RemixI18next to use for `i18n.getFixedT` inside loaders and actions.
  // E.g. The Backend plugin for loading translations from the file system
  // Tip: You could pass `resources` to the `i18next` configuration and avoid a backend here
  plugins: [Backend],
});

export default i18next;

客户端配置

现在在您的 entry.client.tsx 中，将默认代码替换为此代码

import { RemixBrowser } from "@remix-run/react";
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import i18n from "./i18n";
import i18next from "i18next";
import { I18nextProvider, initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import Backend from "i18next-http-backend";
import { getInitialNamespaces } from "remix-i18next/client";

async function hydrate() {
  await i18next
    .use(initReactI18next) // Tell i18next to use the react-i18next plugin
    .use(LanguageDetector) // Setup a client-side language detector
    .use(Backend) // Setup your backend
    .init({
      ...i18n, // spread the configuration
      // This function detects the namespaces your routes rendered while SSR use
      ns: getInitialNamespaces(),
      backend: { loadPath: "/locales/{{lng}}/{{ns}}.json" },
      detection: {
        // Here only enable htmlTag detection, we'll detect the language only
        // server-side with remix-i18next, by using the `<html lang>` attribute
        // we can communicate to the client the language detected server-side
        order: ["htmlTag"],
        // Because we only use htmlTag, there's no reason to cache the language
        // on the browser, so we disable it
        caches: [],
      },
    });

  startTransition(() => {
    hydrateRoot(
      document,
      <I18nextProvider i18n={i18next}>
        <StrictMode>
          <RemixBrowser />
        </StrictMode>
      </I18nextProvider>
    );
  });
}

if (window.requestIdleCallback) {
  window.requestIdleCallback(hydrate);
} else {
  // Safari doesn't support requestIdleCallback
  // https://caniuse.cn/requestidlecallback
  window.setTimeout(hydrate, 1);
}

服务端配置

在您的 entry.server.tsx 中，将代码替换为此代码

import { PassThrough } from "stream";
import {
  createReadableStreamFromReadable,
  type EntryContext,
} from "@remix-run/node";
import { RemixServer } from "@remix-run/react";
import { isbot } from "isbot";
import { renderToPipeableStream } from "react-dom/server";
import { createInstance } from "i18next";
import i18next from "./i18next.server";
import { I18nextProvider, initReactI18next } from "react-i18next";
import Backend from "i18next-fs-backend";
import i18n from "./i18n"; // your i18n configuration file
import { resolve } from "node:path";

const ABORT_DELAY = 5000;

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  let callbackName = isbot(request.headers.get("user-agent"))
    ? "onAllReady"
    : "onShellReady";

  let instance = createInstance();
  let lng = await i18next.getLocale(request);
  let ns = i18next.getRouteNamespaces(remixContext);

  await instance
    .use(initReactI18next) // Tell our instance to use react-i18next
    .use(Backend) // Setup our backend
    .init({
      ...i18n, // spread the configuration
      lng, // The locale we detected above
      ns, // The namespaces the routes about to render wants to use
      backend: { loadPath: resolve("./public/locales/{{lng}}/{{ns}}.json") },
    });

  return new Promise((resolve, reject) => {
    let didError = false;

    let { pipe, abort } = renderToPipeableStream(
      <I18nextProvider i18n={instance}>
        <RemixServer context={remixContext} url={request.url} />
      </I18nextProvider>,
      {
        [callbackName]: () => {
          let body = new PassThrough();
          const stream = createReadableStreamFromReadable(body);
          responseHeaders.set("Content-Type", "text/html");

          resolve(
            new Response(stream, {
              headers: responseHeaders,
              status: didError ? 500 : responseStatusCode,
            })
          );

          pipe(body);
        },
        onShellError(error: unknown) {
          reject(error);
        },
        onError(error: unknown) {
          didError = true;

          console.error(error);
        },
      }
    );

    setTimeout(abort, ABORT_DELAY);
  });
}

用法

现在，在您的 app/root.tsx 或 app/root.jsx 文件中，如果您没有加载器，请使用以下代码创建一个加载器。

import { useChangeLanguage } from "remix-i18next/react";
import { useTranslation } from "react-i18next";
import i18next from "~/i18next.server";

export async function loader({ request }: LoaderArgs) {
  let locale = await i18next.getLocale(request);
  return json({ locale });
}

export let handle = {
  // In the handle export, we can add a i18n key with namespaces our route
  // will need to load. This key can be a single string or an array of strings.
  // TIP: In most cases, you should set this to your defaultNS from your i18n config
  // or if you did not set one, set it to the i18next default namespace "translation"
  i18n: "common",
};

export default function Root() {
  // Get the locale from the loader
  let { locale } = useLoaderData<typeof loader>();

  let { i18n } = useTranslation();

  // This hook will change the i18n instance language to the current locale
  // detected by the loader, this way, when we do something to change the
  // language, this locale will change and i18next will load the correct
  // translation files
  useChangeLanguage(locale);

  return (
    <html lang={locale} dir={i18n.dir()}>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
        <LiveReload />
      </body>
    </html>
  );
}

最后，在您想要翻译的任何路由中，您可以按照i18next 文档使用 t() 函数，并使用来自默认命名空间的翻译。

import { useTranslation } from "react-i18next";

export default function Component() {
  let { t } = useTranslation();
  return <h1>{t("greeting")}</h1>;
}

如果您希望拆分您的翻译文件，您可以创建新的翻译文件，例如

public/locales/en/home.json

{
  "title": "remix-i18n is awesome"
}

public/locales/es/home.json

{
  "title": "remix-i18n es increíble"
}

并在您的路由中使用它们

import { useTranslation } from "react-i18next";

// This tells remix to load the "home" namespace
export let handle = { i18n: "home" };

export default function Component() {
  let { t } = useTranslation("home");
  return <h1>{t("title")}</h1>;
}

就是这样，对于您想要翻译的每个路由，重复最后一步，remix-i18next 将自动让 i18next 知道要使用哪些命名空间和语言，并且它将使用您配置的后端加载正确的翻译文件。

在加载器或操作内部翻译文本

如果您需要在加载器或操作函数内部获取翻译的文本，例如为了翻译稍后在 MetaFunction 中使用的页面标题，您可以使用 i18n.getFixedT 方法获取 t 函数。

export async function loader({ request }: LoaderArgs) {
  let t = await i18n.getFixedT(request);
  let title = t("My page title");
  return json({ title });
}

export let meta: MetaFunction = ({ data }) => {
  return { title: data.title };
};

可以使用参数组合调用 getFixedT 函数

getFixedT(request)：将使用请求来获取区域设置和在配置中设置的 defaultNS 或 translation ( i18next 默认命名空间 )
getFixedT("es")：将使用指定的 es 区域设置和配置中设置的 defaultNS，或 translation (i18next 默认命名空间)
getFixedT(request, "common") 将使用请求获取区域设置，并使用指定的 common 命名空间来获取翻译。
getFixedT("es", "common") 将使用指定的 es 区域设置和指定的 common 命名空间来获取翻译。
getFixedT(request, "common", { keySeparator: false }) 将使用请求获取区域设置，并使用 common 命名空间来获取翻译，还可以使用第三个参数的选项来初始化 i18next 实例。
getFixedT("es", "common", { keySeparator: false }) 将使用指定的 es 区域设置和 common 命名空间来获取翻译，还可以使用第三个参数的选项来初始化 i18next 实例。

如果您始终需要设置相同的 i18next 选项，您可以在创建新实例时将其传递给 RemixI18Next。

export let i18n = new RemixI18Next({
  detection: { supportedLanguages: ["es", "en"], fallbackLanguage: "en" },
  // The config here will be used for getFixedT
  i18next: {
    backend: { loadPath: resolve("./public/locales/{{lng}}/{{ns}}.json") },
  },
  // This backend will be used by getFixedT
  backend: Backend,
});

此选项将被提供给 getFixedT 的选项覆盖。

使用 `getFixedT` 的 `keyPrefix` 选项

getFixedT 函数现在支持 keyPrefix 选项，允许您在翻译键前面添加前缀。当您想要命名翻译空间而不必每次都指定完整的键路径时，这尤其有用。

以下是如何使用它

export async function loader({ request }: LoaderArgs) {
  // Assuming "greetings" namespace and "welcome" keyPrefix
  let t = await i18n.getFixedT(request, "greetings", { keyPrefix: "welcome" });
  let message = t("user"); // This will look for the "welcome.user" key in your "greetings" namespace
  return json({ message });
}

此功能简化了处理深度嵌套的翻译键，并增强了翻译文件的组织性。

从请求 URL 路径名查找区域设置

如果您想在路径名中保留用户区域设置，您有两种可能的选择。

第一种选择是将加载器/操作参数中的参数传递给 getFixedT。这样您将停止使用 remix-i18next 的语言检测功能。

第二种选择是将 findLocale 函数传递给 RemixI18Next 中的检测选项。

export let i18n = new RemixI18Next({
  detection: {
    supportedLanguages: ["es", "en"],
    fallbackLanguage: "en",
    async findLocale(request) {
      let locale = request.url.pathname.split("/").at(1);
      return locale;
    },
  },
});

findLocale 返回的区域设置将根据支持的区域设置列表进行验证，如果无效，将使用回退区域设置。

从数据库查询区域设置

如果您的应用程序将用户区域设置存储在数据库中，您可以使用 findLocale 函数来查询数据库并返回区域设置。

export let i18n = new RemixI18Next({
  detection: {
    supportedLanguages: ["es", "en"],
    fallbackLanguage: "en",
    async findLocale(request) {
      let user = await db.getUser(request);
      return user.locale;
    },
  },
});

请注意，每次调用 getLocale 和 getFixedT 都会调用 findLocale，因此保持其尽可能快非常重要。

如果您既需要区域设置又需要 t 函数，您可以调用 getLocale，并将结果传递给 getFixedT。