Cách biến ứng dụng Next.js hiện tại thành đa ngôn ngữ (i18n) (hướng dẫn i18n 2026)

Kiểm tra Bản Mẫu Ứng dụng trên GitHub.

Mục lục

Tại sao việc quốc tế hóa một ứng dụng đã tồn tại lại khó khăn?

Nếu bạn đã từng thử thêm nhiều ngôn ngữ vào một ứng dụng trước đây chỉ được xây dựng cho một ngôn ngữ duy nhất, bạn sẽ biết được những rắc rối. Nó không chỉ đơn thuần là "khó khăn" - nó rất tẻ nhạt. Bạn phải xem qua từng tệp, tìm mọi chuỗi văn bản và di chuyển chúng vào các tệp từ điển riêng biệt.

Sau đó là phần rủi ro: thay thế toàn bộ văn bản đó bằng các móc mã mà không làm hỏng bố cục hay logic. Đó là loại công việc có thể làm đình trệ quá trình phát triển tính năng mới trong hàng tuần lễ và cảm giác như một cuộc tái cấu trúc không hồi kết.

Intlayer Compiler là gì?

Intlayer Compiler được tạo ra để bỏ qua những công việc thủ công đó. Thay vì ép bạn trích xuất chuỗi một cách thủ công, trình biên dịch thực hiện điều đó cho bạn. Nó quét mã của bạn, tìm văn bản và sử dụng AI để tạo ra các từ điển trong nền. Sau đó, nó sửa đổi mã nguồn của bạn trong quá trình biên dịch để chèn các hook i18n cần thiết. Về cơ bản, bạn tiếp tục viết ứng dụng của mình như thể nó chỉ dùng một ngôn ngữ, và trình biên dịch sẽ xử lý quá trình chuyển đổi đa ngôn ngữ một cách tự nhiên.

Tài liệu về trình biên dịch: /vi/doc/compiler

Hạn chế

Do trình biên dịch thực hiện phân tích và chuyển đổi mã (chèn hook và tạo từ điển) trong thời gian biên dịch, nó có thể làm chậm thời gian build ứng dụng của bạn.

Để hạn chế ảnh hưởng này trong quá trình phát triển năng động (dev mode), bạn có thể thiết lập trình biên dịch thành chế độ 'build-only' hoặc tắt nó khi không cần thiết.

Hướng dẫn từng bước thiết lập Intlayer vào trong ứng dụng Next.js

Bước 1: Cài đặt các thư viện phụ thuộc

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

npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

• intlayer

  Gói cốt lõi cung cấp các công cụ quốc tế hóa để quản lý cấu hình, dịch thuật, khai báo nội dung, chuyển mã 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 Next.js plugin để 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.

Bước 2: Cấu hình cho dự án của bạn

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.VIETNAMESE],    defaultLocale: Locales.VIETNAMESE,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Cho biết trình biên dịch có nên được bật hay không.     */    enabled: true,    /**     * Thư mục đầu ra cho các từ điển được tối ưu hóa.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Chỉ chèn nội dung vào tệp đã tạo, không có khóa.     */    noMetadata: false,    /**     * Tiền tố khóa từ điển     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Cho biết liệu các thành phần có nên được lưu sau khi được chuyển đổi hay không.     * Bằng cách đó, trình biên dịch có thể được chạy một lần duy nhất để chuyển đổi ứng dụng, và sau đó nó có thể được gỡ bỏ.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Đây là một ứng dụng bản đồ đơn giản điển hình",  },};export default config;

Ghi chú: Đảm bảo bạn đã thiết lập OPEN_AI_API_KEY trong các biến môi trường của mình.

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

Bước 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:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* Các cấu hình Next.js bổ sung tùy chọn tại đâ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 từ điển và theo dõi chúng trong chế độ dev. Nó xác định các biến môi trường Intlayer bên trong môi trường Webpack hoặc Turbopack. Ngoài ra, nó cung cấp các alias để tối ưu hóa hiệu suất và hoạt động mượt mà với Server Components.

Cấu hình Babel

Trình biên dịch Intlayer yêu cầu Babel để trích xuất và tối ưu hóa nội dung của bạn. Cập nhật babel.config.js (hoặc babel.config.json) của bạn để bao gồm các plugin Intlayer:

const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

Bước 4: Phát hiện ngôn ngữ trên trang của bạn

Dọn dẹp nội dung RootLayout của bạn và thay thế bằng ví dụ bên dưới:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Bước 5: Khai báo nội dung của bạn (Tự động)

Khi trình biên dịch được bật, bạn không còn cần khai báo các từ điển nội dung (ví dụ: tệp .content.ts) một cách thủ công.

Thay vào đó, bạn chỉ cần viết nội dung của mình dưới dạng các chuỗi ký tự cứng ngay trong mã. Intlayer sẽ quét mã nguồn, tạo bản dịch bằng cách sử dụng nhà cung cấp AI đã cấu hình, và âm thầm thay thế các chuỗi đó bằng nội dung đã được bản địa hóa trong bước compile của quá trình build. Mọi thứ hoàn toàn tự động.

Chỉ cần viết các thành phần của bạn với các chuỗi hardcoded trong ngôn ngữ mặc định và để Intlayer Compiler lo phần còn lại.

Ví dụ về cách page.tsx của bạn sẽ trông như thế nào:

import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Bắt đầu bằng cách chỉnh sửa cái này!</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

{key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditingThis: "Get started by editing this!",    },    fr: {      getStartedByEditingThis: "Commencez par éditer ceci !",    },    vi: {      getStartedByEditingThis: "Bắt đầu bằng cách chỉnh sửa cái này!",    },  }}}

import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditingThis}</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

• IntlayerClientProvider được sử dụng để cung cấp ngôn ngữ cho các thành phần con phía client.

• Trong khi IntlayerServerProvider được sử dụng để cung cấp ngôn ngữ cho các thành phần con phía server.

  Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

(Tùy chọn) Bước 7: Điền các bản dịch còn thiếu

Intlayer cung cấp một công cụ CLI để giúp bạn điền các bản dịch còn thiếu. Bạn có thể sử dụng lệnh intlayer để kiểm tra và điền các bản dịch còn thiếu từ mã của mình.

npx intlayer test         # Kiểm tra xem có thiếu bản dịch không

npx intlayer fill         # Điền các bản dịch còn thiếu

Để biết thêm chi tiết, vui lòng tham khảo tài liệu CLI

(Không bắt buộc) Bước 8: Middleware Proxy cho Router Localized

Nếu bạn muốn tự động chuyển hướng người dùng đến ngôn ngữ ưu thích của họ, hãy thiết lập một middleware proxy:

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

intlayerProxy đượ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 thích hợp như được xác định trong các thiết lập của tệp cấu hình. Thêm vào đó, nó cho phép lưu trữ ngôn ngữ ưu tiên của người dùng trong cookie.

(Không bắt buộc) Bước 9: Thay đổi ngôn ngữ nội dung

Cách khuyên dùng nhất để thay đổi ngôn ngữ nội dung trong Next.js là sử dụng thành phần Link để hướng người dùng đến route với ngôn ngữ tương ứng. Điều này tận dụng tính năng prefetch của Next.js và tránh việc tải lại trang một cách cưỡng ép.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Ngôn ngữ - vd: VI */}              {localeItem}            </span>            <span>              {/* Tên ngôn ngữ bằng chính nó - vd: Tiếng Việt */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Tên ngôn ngữ theo ngôn ngữ hiện tại - vd: Francés (nếu ngôn ngữ hiện tại là Locales.SPANISH) */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Tên ngôn ngữ bằng tiếng Anh - vd: Vietnamese */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Ngoài ra, bạn có thể sử dụng hàm setLocale được cung cấp bởi hook useLocale. Hàm này không cho phép prefetch trang. Kiểm tra tài liệu hook useLocale để biết thêm chi tiết.

(Không bắt buộc) Bước 10: Tối ưu hóa kích thước Bundle

Khi sử dụng next-intlayer, các từ điển mặc định được bao gồm trong bundle cho từng trang. Để tối ưu hóa kích thước bundle, Intlayer cung cấp một plugin SWC tùy chọn giúp thay thế một cách thông minh các lệnh gọi useIntlayer bằng macro. Điều này đảm bảo rằng các từ điển chỉ được bao gồm trong bundle của những trang thực sự sử dụng chúng.

Để bật tính năng tối ưu hóa này, hãy cài đặt gói @intlayer/swc. Sau khi cài đặt, next-intlayer sẽ tự động phát hiện và sử dụng plugin:

npm install @intlayer/swc --save-dev

Lưu ý: Tính năng tối ưu hóa này chỉ khả dụng cho Next.js 13 trở lên.

Lưu ý: Gói này không được cài đặt mặc định vì các plugin SWC vẫn đang ở giai đoạn thử nghiệm trong Next.js. Điều này có thể thay đổi trong tương lai.

Lưu ý: Nếu bạn thiết lập tùy chọn (trong cấu hình từ điển) importMode: 'dynamic' hoặc importMode: 'fetch', nó sẽ phụ thuộc vào Suspense, vì vậy bạn sẽ cần bọc các lệnh gọi useIntlayer trong một ranh giới Suspense. Điều này có nghĩa là bạn không thể sử dụng useIntlayer trực tiếp ở cấp cao nhất của thành phần Page / Layout.

Cấu hình TypeScript

Intlayer sử dụng module augmentation để tận dụng các ưu điểm của TypeScript và làm cho cơ sở mã 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ấu hình TypeScript hiện tại của bạn  "include": [    // ... cấu hình TypeScript hiện tại 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 dùng việc bỏ qua các tệp được tạo bởi Intlayer. Điều này cho phép bạn tránh việc tải chúng lên kho lưu trữ Git của mình.

Để thực hiện việc này, bạn có thể thêm các hướng dẫn sau vào tệp .gitignore của mình:

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

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

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

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 bản dịch.
• Phát hiện lỗi thời gian thực cho các bản dịch còn thiếu.
• Xem trước inline nội dung đã dịch.
• Quick actions để dễ dàng tạo và cập nhật các bản dịch.

Đọc tài liệu Tiện ích mở rộng VS Code của Intlayer để biết hướng dẫn chi tiết về cách sử dụng tiện ích mở rộng.

(Tùy chọn) Bước 1 : Trích xuất nội dung các thành phần của bạ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:

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;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Trích xuất nội dung từ các thành phần vào từ điển   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # Hoặc npm run dev

Đi xa hơn

Để tiến xa hơn, bạn có thể triển khai visual editor hoặc ngoại hóa nội dung của mình bằng cách sử dụng CMS.