Dịch trang web React Router v7 của bạn bằng Intlayer | Quốc tế hóa (i18n)

Hướng dẫn này trình bày cách tích hợp Intlayer để thực hiện quốc tế hóa liền mạch trong các dự án React Router v7 với định tuyến nhận biết locale, hỗ trợ TypeScript và các thực hành phát triển hiện đại.

Table of Contents

Tại sao Intlayer thay thế các lựa chọn thay thế?

So với các giải pháp chính như react-i18next hay i18next, Intlayer là giải pháp đi kèm với các tính năng tối ưu hóa tích hợp như:

Hướng dẫn từng bước để thiết lập Intlayer trong ứng dụng React Router v7

1. 1

   Cài đặt các phụ thuộc

   Cài đặt các gói cần thiết bằng trình quản lý gói bạn ưa thích:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

   • intlayer

     Gói cốt lõi cung cấp các công cụ quốc tế hóa cho quản lý cấu hình, dịch thuật, khai báo nội dung, biên dịch lại, và các lệnh CLI.

   • react-intlayer Gói tích hợp Intlayer với ứng dụng React. Nó cung cấp các context provider và hook cho việc quốc tế hóa trong React.

   • vite-intlayer Bao gồm plugin Vite để tích hợp Intlayer với trình đóng gói Vite, cũng như middleware để phát hiện ngôn ngữ ưu tiên của người dùng, quản lý cookie và xử lý chuyển hướng URL.

2. 2

   Cấu hình dự án của bạn

Hướng dẫn từng bước để thiết lập Intlayer trong ứng dụng React Router v7 với các route dựa trên hệ thống tệp

See Application Template on GitHub.

Tạo một file cấu hình để cấu hình các ngôn ngữ của ứng dụng của bạn:

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH,
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
  },
};

export default config;

Thông qua tệp cấu hình này, bạn có thể thiết lập URL theo ngôn ngữ, chuyển hướng middleware, tên cookie, vị trí và phần mở rộng của các khai báo nội dung, tắt các log của Intlayer trên console, và nhiều hơn nữa. Để xem danh sách đầy đủ các tham số có sẵn, hãy tham khảo tài liệu cấu hình.

1. 3

   Tích hợp Intlayer vào cấu hình Vite của bạn

   Thêm plugin intlayer vào cấu hình của bạn:

   vite.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [reactRouter(), intlayer()],});

   Plugin Vite intlayer() được sử dụng để tích hợp Intlayer với Vite. Nó đảm bảo việc xây dựng các tệp khai báo nội dung và giám sát chúng trong chế độ phát triển. Nó định nghĩa các biến môi trường Intlayer trong ứng dụng Vite. Ngoài ra, nó còn cung cấp các alias để tối ưu hiệu suất.

2. 4

   Cấu hình các Route của React Router v7

   Thiết lập cấu hình routing với các route nhận biết ngôn ngữ:

   app/routes.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { layout, route, type RouteConfig } from "@react-router/dev/routes";export default [  route("/:lang?", "routes/page.tsx"), // Trang chủ có hỗ trợ đa ngôn ngữ  route("/:lang?/about", "routes/about/page.tsx"), // Trang about có hỗ trợ đa ngôn ngữ] satisfies RouteConfig;

3. 5

   Tạo các Component Layout

   Thiết lập root layout và các layout theo ngôn ngữ cụ thể:

   Root Layout

   app/root.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import {  data,  Meta,  Scripts,  ScrollRestoration,  useLoaderData,} from "react-router";import type { Route } from "./+types/root";// ... Unchanged App, links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) {  const locale = getLocaleFromPath(request.url);  if (!locale) {    throw data("Language not supported", { status: 404 });  }  return { locale };}export function Layout({  children,}: { children: React.ReactNode } & Route.ComponentProps) {  const data = useLoaderData<typeof loader>();  const { locale } = data ?? {};  return (    <html lang={locale}>      <head>        <meta charSet="utf-8" />        <meta content="width=device-width, initial-scale=1" name="viewport" />        <Meta />        <Links />      </head>      <body>        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>        <ScrollRestoration />        <Scripts />      </body>    </html>  );}

4. 6

   Khai báo Nội dung của bạn

   Tạo và quản lý các khai báo nội dung để lưu trữ bản dịch:

   app/routes/[lang]/page.content.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    title: t({      en: "Welcome to React Router v7 + Intlayer",      es: "Bienvenido a React Router v7 + Intlayer",      fr: "Bienvenue sur React Router v7 + Intlayer",    }),    description: t({      en: "Xây dựng các ứng dụng đa ngôn ngữ một cách dễ dàng sử dụng React Router v7 và Intlayer.",      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",    }),    aboutLink: t({      en: "Tìm hiểu về chúng tôi",      es: "Aprender Sobre Nosotros",      fr: "En savoir plus sur nous",    }),    homeLink: t({      en: "Trang chủ",      es: "Inicio",      fr: "Accueil",    }),  },} satisfies Dictionary;export default pageContent;

   Các khai báo nội dung của bạn có thể được định nghĩa ở bất kỳ đâu trong ứng dụng của bạn miễn là chúng được bao gồm trong thư mục contentDir (mặc định là ./app). Và phải phù hợp với phần mở rộng của tệp khai báo nội dung (mặc định là .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Để biết thêm chi tiết, hãy tham khảo tài liệu khai báo nội dung.

5. 7

   Tạo các thành phần nhận biết ngôn ngữ

   Tạo một thành phần LocalizedLink để điều hướng nhận biết ngôn ngữ:

   app/components/localized-link.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);export const locacalizeTo = (to: To, locale: LocalesValues): To => {  if (typeof to === "string") {    if (isExternalLink(to)) {      return to;    }    return getLocalizedUrl(to, locale);  }  if (isExternalLink(to.pathname ?? "")) {    return to;  }  return {    ...to,    pathname: getLocalizedUrl(to.pathname ?? "", locale),  };};export const LocalizedLink: FC<LinkProps> = (props) => {  const { locale } = useLocale();  return <Link {...props} to={locacalizeTo(props.to, locale)} />;};

   Trong trường hợp bạn muốn điều hướng đến các route đã được địa phương hóa, bạn có thể sử dụng hook useLocalizedNavigate:

   app/hooks/useLocalizedNavigate.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => {  const navigate = useNavigate();  const { locale } = useLocale();  const localizedNavigate = (to: To, options?: NavigateOptions) => {    const localedTo = locacalizeTo(to, locale);    navigate(localedTo, options);  };  return localizedNavigate;};

6. 8

   Sử dụng Intlayer trong các Trang của Bạn

   Truy cập các từ điển nội dung của bạn trong toàn bộ ứng dụng:

   Trang Chủ Đã Được Địa Phương Hóa

   app/routes/page.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/page";export const loader = ({ params }: Route.LoaderArgs) => {  const { locale } = params;  const { isValid } = validatePrefix(locale);  if (!isValid) {    throw data("Locale not supported", { status: 404 });  }};export const meta: Route.MetaFunction = ({ params }) => {  const content = getIntlayer("page", params.locale);  return [    { title: content.title },    { content: content.description, name: "description" },  ];};export default function Page() {  const { title, description, aboutLink } = useIntlayer("page");  return (    <div>      <h1>{title}</h1>      <p>{description}</p>      <nav>        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>      </nav>    </div>  );}

   Để tìm hiểu thêm về hook useIntlayer, hãy tham khảo tài liệu.

   Nếu ứng dụng của bạn đã tồn tại, bạn có thể sử dụng Intlayer Compiler kết hợp với lệnh extract để chuyển đổi hàng nghìn component chỉ trong một giây.

7. 9

   Tạo Thành Phần Chuyển Đổi Ngôn Ngữ

   Tạo một thành phần cho phép người dùng thay đổi ngôn ngữ:

   app/components/locale-switcher.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { FC } from "react";import {  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,  getPathWithoutLocale,  Locales,} from "intlayer";import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => {  const { localeSwitcherLabel } = useIntlayer("locale-switcher");  const { pathname } = useLocation();  const { availableLocales, locale } = useLocale();  const pathWithoutLocale = getPathWithoutLocale(pathname);  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <Link            aria-current={localeItem === locale ? "page" : undefined}            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}            onClick={() => setLocale(localeItem)}            to={getLocalizedUrl(pathWithoutLocale, localeItem)}          >            <span>              {/* Ngôn ngữ - ví dụ: FR */}              {localeItem}            </span>            <span>              {/* Ngôn ngữ theo Locale riêng của nó - ví dụ: Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Ngôn ngữ theo Locale hiện tại - ví dụ: Francés với locale hiện tại được đặt là Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Ngôn ngữ bằng tiếng Anh - ví dụ: French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        </li>      ))}    </ol>  );};

   Để tìm hiểu thêm về hook useLocale, tham khảo tài liệu.

8. 10

   Thêm quản lý thuộc tính HTML

   Tạo một hook để quản lý các thuộc tính lang và dir của HTML:

   app/hooks/useI18nHTMLAttributes.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    document.documentElement.lang = locale; // đặt thuộc tính lang của thẻ gốc theo locale hiện tại    document.documentElement.dir = getHTMLTextDir(locale); // đặt thuộc tính dir của thẻ gốc theo locale hiện tại  }, [locale]);};

   Sau đó sử dụng nó trong component gốc của bạn:

   app/routes/layout.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // nhập hookexport default function RootLayout() {  useI18nHTMLAttributes(); // gọi hook  return (    <IntlayerProvider>      <Outlet />    </IntlayerProvider>  );}

9. 1

   Trích xuất nội dung các thành phần của bạn

   Tùy chọn

   Nếu bạn có một cơ sở mã hiện có, việc chuyển đổi hàng nghìn tệp có thể tốn nhiều thời gian.

   Để đơn giản hóa quy trình này, Intlayer đề xuất một trình biên dịch / trình trích xuất để chuyển đổi các thành phần của bạn và trích xuất nội dung.

   Để thiết lập, bạn có thể thêm phần compiler vào tệp intlayer.config.ts của mình:

   intlayer.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     // ... Phần còn lại của cấu hình
     compiler: {
       /**
        * Cho biết trình biên dịch có nên được bật hay không.
        */
       enabled: true,
   
       /**
        * Xác định đường dẫn các tệp đầu ra
        */
       output: ({ fileName, extension }) => `./${fileName}${extension}`,
   
       /**
        * Cho biết các thành phần có nên được lưu sau khi chuyển đổi hay không. Bằng cách đó, trình biên dịch có thể được chạy chỉ một lần để chuyển đổi ứng dụng, sau đó có thể được gỡ bỏ.
        */
       saveComponents: false,
   
       /**
        * Tiền tố khóa từ điển
        */
       dictionaryKeyPrefix: "",
     },
   };
   
   export default config;

   Lệnh trích xuấtTrình biên dịch Babel

   Chạy trình trích xuất để chuyển đổi các thành phần và trích xuất nội dung

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npx intlayer extract

   Cập nhật vite.config.ts của bạn để bao gồm plugin intlayerCompiler:

   vite.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Thêm plugin trình biên dịch ],});

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm run build # Hoặc npm run dev

   ---

Configure TypeScript

Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types:

{  // ... your existing configurations  include: [    // ... your existing includes    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

# Ignore the files generated by Intlayer.intlayer

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

To go further, you can implement the visual editor or externalize your content using the CMS.

Documentation References

• Intlayer Documentation
• React Router v7 Documentation
• useIntlayer hook
• useLocale hook
• Content Declaration
• Configuration

This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 for a fully internationalized application with locale-aware routing and TypeScript support.

1. 11

   Thêm middleware

   Bạn cũng có thể sử dụng intlayerProxy để thêm routing phía server cho ứng dụng của bạn. Plugin này sẽ tự động phát hiện locale hiện tại dựa trên URL và thiết lập cookie locale phù hợp. Nếu không có locale nào được chỉ định, plugin sẽ xác định locale phù hợp nhất dựa trên ngôn ngữ trình duyệt của người dùng. Nếu không phát hiện được locale nào, nó sẽ chuyển hướng đến locale mặc định.

   Lưu ý rằng để sử dụng intlayerProxy trong môi trường production, bạn cần chuyển gói vite-intlayer từ devDependencies sang dependencies.

   vite.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    reactRouter(),    intlayer(),  ],});

   ---

Cấu hình TypeScript

Intlayer sử dụng module augmentation để tận dụng các lợi ích của TypeScript và làm cho codebase của bạn mạnh mẽ hơn.

Đảm bảo cấu hình TypeScript của bạn bao gồm các kiểu được tạo tự động:

{  // ... các cấu hình hiện có của bạn  include: [    // ... các phần include hiện có của bạn    ".intlayer/**/*.ts", // Bao gồm các kiểu được tạo tự động  ],}

Cấu hình Git

Khuyến nghị bỏ qua các tệp được tạo bởi Intlayer. Điều này giúp bạn tránh việc commit chúng vào kho Git của mình.

Để làm điều này, bạn có thể thêm các hướng dẫn sau vào tệp .gitignore của bạn:

# Bỏ qua các tệp được tạo bởi Intlayer.intlayer

Tiện ích mở rộng VS Code

Để cải thiện trải nghiệm phát triển với Intlayer, bạn có thể cài đặt Tiện ích mở rộng Intlayer cho VS Code chính thức.

Cài đặt từ VS Code Marketplace

Tiện ích mở rộng này cung cấp:

• Tự động hoàn thành cho các khóa dịch.
• Phát hiện lỗi thời gian thực cho các bản dịch bị thiếu.
• Xem trước nội dung dịch ngay trong dòng.
• Hành động nhanh để dễ dàng tạo và cập nhật bản dịch.

Để biết thêm chi tiết về cách sử dụng tiện ích mở rộng, hãy tham khảo Tài liệu Tiện ích mở rộng VS Code của Intlayer.

Đi xa hơn

Để đi xa hơn, bạn có thể triển khai trình chỉnh sửa trực quan hoặc tách nội dung của bạn ra ngoài bằng cách sử dụng CMS.

Tham khảo Tài liệu

• Tài liệu Intlayer
• Tài liệu React Router v7
• useIntlayer hook
• useLocale hook
• Khai báo nội dung
• Cấu hình

Hướng dẫn toàn diện này cung cấp tất cả những gì bạn cần để tích hợp Intlayer với React Router v7 cho một ứng dụng được quốc tế hóa hoàn chỉnh với định tuyến nhận biết locale và hỗ trợ TypeScript.