Dịch trang web Next.js 15 của bạn bằng Intlayer | Quốc tế hóa (i18n)

Mục lục

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ư next-intl 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 Để Cài Đặt Intlayer Trong Ứng Dụng Next.js

Xem Application Template trên GitHub.

1. 1

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

   Cài đặt các gói cần thiết bằng npm:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm install intlayer next-intlayernpx 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.

   • next-intlayer

     Gói tích hợp Intlayer với Next.js. Nó cung cấp các context provider và hook cho quốc tế hóa Next.js. Ngoài ra, nó bao gồm plugin Next.js để tích hợp Intlayer với Webpack hoặc Turbopack, cũng như middleware để phát hiện locale ư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

   Here is the final structure that we will make:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   .├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── middleware.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

   If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

   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:

   intlayer.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Các ngôn ngữ khác của bạn
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Thông qua tệp cấu hình này, bạn có thể thiết lập URL địa phương hóa, 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.

3. 3

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

   Cấu hình thiết lập Next.js của bạn để sử dụng Intlayer:

   next.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { NextConfig } from "next";
   import { withIntlayer } from "next-intlayer/server";
   
   const nextConfig: NextConfig = {
     /* các tùy chọn cấu hình ở đây */
   };
   
   export default withIntlayer(nextConfig);

   Plugin Next.js withIntlayer() được sử dụng để tích hợp Intlayer với Next.js. 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 môi trường Webpack hoặc Turbopack. Ngoài ra, nó cung cấp các bí danh để tối ưu hiệu suất và đảm bảo tương thích với các thành phần server.

   Hàm withIntlayer() là một hàm promise. Nó cho phép chuẩn bị các từ điển intlayer trước khi quá trình build bắt đầu. Nếu bạn muốn sử dụng nó cùng với các plugin khác, bạn có thể dùng await. Ví dụ:

   tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

   Nếu bạn muốn sử dụng nó một cách đồng bộ, bạn có thể dùng hàm withIntlayerSync(). Ví dụ:

   tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

4. 4

   Định nghĩa các tuyến đường Locale động

   Xóa tất cả mọi thứ trong RootLayout và thay thế bằng đoạn mã sau:

   src/app/layout.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { PropsWithChildren, FC } from "react";
   import "./globals.css";
   
   const RootLayout: FC<PropsWithChildren> = ({ children }) => (
     // Bạn vẫn có thể bao bọc các children với các provider khác, như `next-themes`, `react-query`, `framer-motion`, v.v.
     <>{children}</>
   );
   
   export default RootLayout;

   Giữ cho component RootLayout trống cho phép thiết lập các thuộc tính lang và dir trên thẻ <html>.

   Để triển khai dynamic routing, cung cấp đường dẫn cho locale bằng cách thêm một layout mới trong thư mục [locale] của bạn:

   src/app/[locale]/layout.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
     const { locale } = await params;
     return (
       <html lang={locale} dir={getHTMLTextDir(locale)}>
         <body className={inter.className}>
           <IntlayerClientProvider locale={locale}>
             {children}
           </IntlayerClientProvider>
         </body>
       </html>
     );
   };
   
   export default LocaleLayout;

   Đoạn đường dẫn [locale] được sử dụng để xác định locale. Ví dụ: /en-US/about sẽ tham chiếu đến en-US và /fr/about sẽ tham chiếu đến fr.

   Ở giai đoạn này, bạn sẽ gặp lỗi: Error: Missing <html> and <body> tags in the root layout.. Điều này là bình thường vì file /app/page.tsx không còn được sử dụng và có thể xóa bỏ. Thay vào đó, phân đoạn đường dẫn [locale] sẽ kích hoạt trang /app/[locale]/page.tsx. Do đó, các trang sẽ có thể truy cập qua các đường dẫn như /en, /fr, /es trên trình duyệt của bạn. Để đặt locale mặc định làm trang gốc, hãy tham khảo thiết lập middleware trong bước 7.

   Sau đó, triển khai hàm generateStaticParams trong Layout ứng dụng của bạn.

   src/app/[locale]/layout.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   export { generateStaticParams } from "next-intlayer"; // Dòng cần chènconst LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {  /*... Phần còn lại của mã */};export default LocaleLayout;

   generateStaticParams đảm bảo rằng ứng dụng của bạn xây dựng trước các trang cần thiết cho tất cả các ngôn ngữ, giảm thiểu tính toán khi chạy và cải thiện trải nghiệm người dùng. Để biết thêm chi tiết, hãy tham khảo tài liệu Next.js về generateStaticParams.

   Intlayer hoạt động với export const dynamic = 'force-static'; để đảm bảo các trang được xây dựng trước cho tất cả các ngôn ngữ.

5. 5

   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:

   src/app/[locale]/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: {
       getStarted: {
         main: t({
           en: "Get started by editing",
           fr: "Commencez par éditer",
           es: "Comience por editar",
         }),
         pageLink: "src/app/page.tsx",
       },
     },
   } 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 đưa vào thư mục contentDir (mặc định là ./src). 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.

6. 6

   Sử dụng Nội dung trong Mã 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:

   src/app/[locale]/page.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { FC } from "react";
   import { ClientComponentExample } from "@components/ClientComponentExample";
   import { ServerComponentExample } from "@components/ServerComponentExample";
   import { type NextPageIntlayer } from "next-intlayer";
   import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
   
   const PageContent: FC = () => {
     const content = useIntlayer("page");
   
     return (
       <>
         <p>{content.getStarted.main}</p> {/* Nội dung chính để bắt đầu */}
         <code>{content.getStarted.pageLink}</code>{" "}
         {/* Liên kết trang để bắt đầu */}
       </>
     );
   };
   
   const Page: NextPageIntlayer = async ({ params }) => {
     const { locale } = await params;
   
     return (
       <IntlayerServerProvider locale={locale}>
         <PageContent />
         <ServerComponentExample />
   
         <ClientComponentExample />
       </IntlayerServerProvider>
     );
   };
   
   export default Page;

   • IntlayerClientProvider được sử dụng để cung cấp locale cho các component phía client. Nó có thể được đặt trong bất kỳ component cha nào, bao gồm cả layout. Tuy nhiên, việc đặt nó trong layout được khuyến nghị vì Next.js chia sẻ mã layout giữa các trang, giúp hiệu quả hơn. Bằng cách sử dụng IntlayerClientProvider trong layout, bạn tránh việc khởi tạo lại cho mỗi trang, cải thiện hiệu suất và duy trì ngữ cảnh localization nhất quán trong toàn bộ ứng dụng của bạn.

   • IntlayerServerProvider được sử dụng để cung cấp locale cho các component con phía server. Nó không thể được đặt trong layout.

     Layout và trang không thể chia sẻ một ngữ cảnh server chung vì hệ thống ngữ cảnh server dựa trên kho dữ liệu theo từng yêu cầu (thông qua cơ chế React's cache), khiến mỗi "context" được tạo lại cho các phân đoạn khác nhau của ứng dụng. Việc đặt provider trong một layout dùng chung sẽ phá vỡ sự cô lập này, ngăn cản việc truyền đúng giá trị ngữ cảnh server đến các component server của bạn.

     Layout và trang không thể chia sẻ một context server chung vì hệ thống context server dựa trên kho dữ liệu theo từng yêu cầu (qua cơ chế React's cache), dẫn đến mỗi "context" được tạo lại cho các phân đoạn khác nhau của ứng dụng. Việc đặt provider trong một layout dùng chung sẽ phá vỡ sự cô lập này, ngăn cản việc truyền đúng các giá trị context server đến các component server của bạn.

   src/components/ClientComponentExample.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   "use client";
   
   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   export const ClientComponentExample: FC = () => {
     const content = useIntlayer("client-component-example"); // Tạo khai báo nội dung liên quan
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };

   src/components/ServerComponentExample.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer/server";
   
   export const ServerComponentExample: FC = () => {
     const content = useIntlayer("server-component-example"); // Tạo khai báo nội dung liên quan
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };

   Nếu bạn muốn sử dụng nội dung của mình trong một thuộc tính string, như alt, title, href, aria-label, v.v., bạn phải gọi giá trị của hàm, ví dụ:

   html

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

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

7. 7

   Cấu hình Middleware để Phát hiện Ngôn ngữ

   Tùy chọn

   Thiết lập middleware để phát hiện ngôn ngữ ưu tiên của người dùng:

   src/middleware.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
   
   export const config = {
     matcher:
       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
   };

   intlayerMiddleware được sử dụng để phát hiện ngôn ngữ ưu tiên của người dùng và chuyển hướng họ đến URL phù hợp như được chỉ định trong cấu hình. Ngoài ra, nó còn cho phép lưu ngôn ngữ ưu tiên của người dùng trong cookie.

   Nếu bạn cần kết hợp nhiều middleware với nhau (ví dụ, intlayerMiddleware cùng với middleware xác thực hoặc middleware tùy chỉnh), Intlayer hiện cung cấp một helper gọi là multipleMiddlewares.

   ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import {  multipleMiddlewares,  intlayerMiddleware,} from "next-intlayer/middleware";import { customMiddleware } from "@utils/customMiddleware";export const middleware = multipleMiddlewares([  intlayerMiddleware,  customMiddleware,]);

8. 8

   Quốc tế hóa metadata của bạn

   Tùy chọn

   Trong trường hợp bạn muốn quốc tế hóa metadata của mình, chẳng hạn như tiêu đề trang, bạn có thể sử dụng hàm generateMetadata do Next.js cung cấp. Bên trong, bạn có thể lấy nội dung từ hàm getIntlayer để dịch metadata của bạn.

   src/app/[locale]/metadata.content.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { type Dictionary, t } from "intlayer";
   import { Metadata } from "next";
   
   const metadataContent = {
     key: "page-metadata",
     content: {
       title: t({
         en: "Create Next App",
         fr: "Créer une application Next.js",
         es: "Crear una aplicación Next.js",
         vi: "Tạo ứng dụng Next",
       }),
       description: t({
         en: "Generated by create next app",
         fr: "Généré par create next app",
         es: "Generado por create next app",
         vi: "Được tạo bởi create next app",
       }),
     },
   } satisfies Dictionary<Metadata>;
   
   export default metadataContent;

   src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { getIntlayer, getMultilingualUrls } from "intlayer";
   import type { Metadata } from "next";
   import type { LocalPromiseParams } from "next-intlayer";
   
   export const generateMetadata = async ({
     params,
   }: LocalPromiseParams): Promise<Metadata> => {
     const { locale } = await params;
   
     const metadata = getIntlayer("page-metadata", locale);
   
     /**
      * Tạo một đối tượng chứa tất cả các url cho mỗi ngôn ngữ.
      *
      * Ví dụ:
      * ```ts
      *  getMultilingualUrls('/about');
      *
      *  // Trả về
      *  // {
      *  //   en: '/about',
      *  //   fr: '/fr/about',
      *  //   es: '/es/about',
      *  // }
      * ```
      */
     const multilingualUrls = getMultilingualUrls("/");
     const localizedUrl =
       multilingualUrls[locale as keyof typeof multilingualUrls];
   
     return {
       ...metadata,
       alternates: {
         canonical: localizedUrl,
         languages: { ...multilingualUrls, "x-default": "/" },
       },
       openGraph: {
         url: localizedUrl,
       },
     };
   };
   
   // ... Phần còn lại của mã