Nhận thông báo về các bản phát hành sắp tới của Intlayer
    Ngày tạo:2025-08-23Cập nhật lần cuối:2025-08-23

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

    Xem Application Template trên GitHub.

    Intlayer là gì?

    Intlayer là một thư viện quốc tế hóa (i18n) mã nguồn mở, sáng tạo, được thiết kế để đơn giản hóa việc hỗ trợ đa ngôn ngữ trong các ứng dụng web hiện đại.

    Với Intlayer, bạn có thể:

    • Quản lý bản dịch dễ dàng bằng cách sử dụng từ điển khai báo ở cấp độ component.
    • Địa phương hóa động metadata, routes và nội dung.
    • Đảm bảo hỗ trợ TypeScript với các kiểu tự động tạo, cải thiện tự động hoàn thành và phát hiện lỗi.
    • Hưởng lợi từ các tính năng nâng cao, như phát hiện và chuyển đổi locale động.

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

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

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

    npm install intlayer react-intlayer react-scripts-intlayer
    • 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 providers và hooks cho quốc tế hóa trong React.

    • react-scripts-intlayer

      Bao gồm các lệnh react-scripts-intlayer và các plugin để tích hợp Intlayer với ứng dụng dựa trên Create React App. Các plugin này dựa trên craco và bao gồm cấu hình bổ sung cho bộ đóng gói Webpack.

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

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

    intlayer.config.ts
    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 của bạn, tắt các log của Intlayer trong 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.

    Bước 3: Tích hợp Intlayer vào Cấu hình CRA của Bạn

    Thay đổi các script của bạn để sử dụng react-intlayer

    package.json
      "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },
    Các script react-scripts-intlayer dựa trên CRACO. Bạn cũng có thể tự thiết lập dựa trên plugin craco của intlayer. Xem ví dụ tại đây.

    Bước 4: 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.content.tsx
    import { t, type Dictionary } from "intlayer";import React, { type ReactNode } from "react";const appContent = {  key: "app",  content: {    getStarted: t<ReactNode>({      en: (        <>          Chỉnh sửa <code>src/App.tsx</code> và lưu để tải lại        </>      ),      fr: (        <>          Éditez <code>src/App.tsx</code> et enregistrez pour recharger        </>      ),      es: (        <>          Chỉnh sửa <code>src/App.tsx</code> và lưu để tải lại        </>      ),    }),    reactLink: {      href: "https://reactjs.org",      content: t({        en: "Học React",        fr: "Apprendre React",        es: "Aprender React",      }),    },  },} satisfies Dictionary;export default appContent;
    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 khớ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,mjx,cjs,cjx}).
    Để biết thêm chi tiết, tham khảo tài liệu khai báo nội dung.
    Nếu tệp nội dung của bạn bao gồm mã TSX, bạn nên cân nhắc nhập import React from "react"; trong tệp nội dung của bạn.

    Bước 5: Sử dụng Intlayer 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.tsx
    import logo from "./logo.svg";import "./App.css";import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => {  const content = useIntlayer("app");  return (    <div className="App">      <img src={logo} className="App-logo" alt="logo" />      {content.getStarted}      <a        className="App-link"        href={content.reactLink.href.value}        target="_blank"        rel="noopener noreferrer"      >        {content.reactLink.content}      </a>    </div>  );};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;
    Lưu ý: Nếu bạn muốn sử dụng nội dung của mình trong một thuộc tính string, chẳng hạn như alt, title, href, aria-label, v.v., bạn phải gọi giá trị của hàm, ví dụ:
    <img src={content.image.src.value} alt={content.image.value} />
    Để tìm hiểu thêm về hook useIntlayer, hãy tham khảo tài liệu.

    (Tùy chọn) Bước 6: Thay đổi ngôn ngữ của nội dung

    Để thay đổi ngôn ngữ của nội dung, bạn có thể sử dụng hàm setLocale được cung cấp bởi hook useLocale. Hàm này cho phép bạn thiết lập locale của ứng dụng và cập nhật nội dung tương ứng.

    src/components/LocaleSwitcher.tsx
    import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Change Language to English    </button>  );};
    Để tìm hiểu thêm về hook useLocale, hãy tham khảo tài liệu.

    (Tùy chọn) Bước 7: Thêm định tuyến theo ngôn ngữ vào ứng dụng của bạn

    Mục đích của bước này là tạo các đường dẫn duy nhất cho mỗi ngôn ngữ. Điều này hữu ích cho SEO và các URL thân thiện với SEO. Ví dụ:

    - https://example.com/about- https://example.com/es/about- https://example.com/fr/about
    Theo mặc định, các đường dẫn không được thêm tiền tố cho locale mặc định. Nếu bạn muốn thêm tiền tố cho locale mặc định, bạn có thể đặt tùy chọn middleware.prefixDefault thành true trong cấu hình của bạn. Xem thêm trong tài liệu cấu hình để biết thêm thông tin.

    Để thêm định tuyến theo ngôn ngữ vào ứng dụng của bạn, bạn có thể tạo một component LocaleRouter bao bọc các route của ứng dụng và xử lý định tuyến dựa trên locale. Dưới đây là ví dụ sử dụng React Router:

    src/components/LocaleRouter.tsx
    // Import các dependencies và hàm cần thiếtimport { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Các hàm tiện ích và kiểu từ 'intlayer'// Các hàm tiện ích và kiểu từ 'intlayer'import type { FC, PropsWithChildren } from "react"; // Kiểu React cho các functional component và propsimport { IntlayerProvider } from "react-intlayer"; // Provider cho ngữ cảnh quốc tế hóaimport {  BrowserRouter,  Routes,  Route,  Navigate,  useLocation,} from "react-router-dom"; // Các component router để quản lý điều hướng// Lấy cấu hình từ Intlayerconst { internationalization, middleware } = configuration;const { locales, defaultLocale } = internationalization;/** * Một component xử lý việc địa phương hóa và bao bọc các children với ngữ cảnh locale phù hợp. * Nó quản lý việc phát hiện và xác thực locale dựa trên URL. */const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({  children,  locale,}) => {  const { pathname, search } = useLocation(); // Lấy đường dẫn URL hiện tại  // Xác định locale hiện tại, nếu không có thì dùng locale mặc định  const currentLocale = locale ?? defaultLocale;  // Loại bỏ tiền tố locale khỏi đường dẫn để tạo đường dẫn cơ sở  const pathWithoutLocale = getPathWithoutLocale(    pathname // Đường dẫn URL hiện tại  );  /**   * Nếu middleware.prefixDefault là true, locale mặc định luôn phải có tiền tố.   */  if (middleware.prefixDefault) {    // Xác thực locale    if (!locale || !locales.includes(locale)) {      // Chuyển hướng đến locale mặc định với đường dẫn đã cập nhật      return (        <Navigate          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}          replace // Thay thế mục lịch sử hiện tại bằng mục mới        />      );    }    // Bao bọc children với IntlayerProvider và đặt locale hiện tại    return (      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>    );  } else {    /**     * Khi middleware.prefixDefault là false, locale mặc định không có tiền tố.     * Đảm bảo locale hiện tại hợp lệ và không phải là locale mặc định.     */    if (      currentLocale.toString() !== defaultLocale.toString() &&      !locales        .filter(          (locale) => locale.toString() !== defaultLocale.toString() // Loại trừ locale mặc định        )        .includes(currentLocale) // Kiểm tra xem locale hiện tại có trong danh sách các locale hợp lệ không    ) {      // Chuyển hướng đến đường dẫn không có tiền tố locale      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;    }    // Bao bọc children với IntlayerProvider và đặt locale hiện tại    return (      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>    );  }};/** * Một component router thiết lập các tuyến đường theo locale cụ thể. * Nó sử dụng React Router để quản lý điều hướng và render các component đã được bản địa hóa. */export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (  <BrowserRouter>    <Routes>      {locales        .filter(          (locale) => middleware.prefixDefault || locale !== defaultLocale        )        .map((locale) => (          <Route            // Mẫu tuyến đường để bắt locale (ví dụ: /en/, /fr/) và khớp với tất cả các đường dẫn tiếp theo            path={`/${locale}/*`}            key={locale}            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Bao bọc children với quản lý locale          />        ))}      {        // Nếu không bật tiền tố cho locale mặc định, render trực tiếp children tại đường dẫn gốc        !middleware.prefixDefault && (          <Route            path="*"            element={              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>            } // Bao bọc children với quản lý locale          />        )      }    </Routes>  </BrowserRouter>);

    Sau đó, bạn có thể sử dụng component LocaleRouter trong ứng dụng của mình:

    src/App.tsx
    import { LocaleRouter } from "./components/LocaleRouter";import type { FC } from "react";// ... Component AppContent của bạnconst App: FC = () => (  <LocaleRouter>    <AppContent />  </LocaleRouter>);

    (Tùy chọn) Bước 8: Thay đổi URL khi locale thay đổi

    Để thay đổi URL khi locale thay đổi, bạn có thể sử dụng prop onLocaleChange được cung cấp bởi hook useLocale. Đồng thời, bạn có thể sử dụng các hook useLocationuseNavigate từ react-router-dom để cập nhật đường dẫn URL.

    src/components/LocaleSwitcher.tsx
    import { useLocation, useNavigate } from "react-router-dom";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "react-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { pathname, search } = useLocation(); // Lấy đường dẫn URL hiện tại. Ví dụ: /fr/about?foo=bar  const navigate = useNavigate();  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (locale) => {      // Tạo URL với locale được cập nhật      // Ví dụ: /es/about?foo=bar      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);      // Cập nhật đường dẫn URL      navigate(pathWithLocale);    },  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <a            href={getLocalizedUrl(location.pathname, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}            key={localeItem}          >            <span>              {/* Ngôn ngữ - ví dụ: FR */}              {localeItem}            </span>            <span>              {/* Ngôn ngữ trong chính ngôn ngữ đó - ví dụ: Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Ngôn ngữ trong ngôn ngữ hiện tại - ví dụ: Francés với ngôn ngữ hiện tại 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>          </a>        ))}      </div>    </div>  );};

    Tham khảo tài liệu:

    (Tùy chọn) Bước 9: Chuyển đổi Thuộc tính Ngôn ngữ và Hướng của HTML

    Khi ứng dụng của bạn hỗ trợ nhiều ngôn ngữ, việc cập nhật các thuộc tính langdir của thẻ <html> để phù hợp với locale hiện tại là điều rất quan trọng. Việc này đảm bảo:

    • Khả năng truy cập: Trình đọc màn hình và các công nghệ hỗ trợ dựa vào thuộc tính lang chính xác để phát âm và diễn giải nội dung một cách chính xác.
    • Hiển thị văn bản: Thuộc tính dir (hướng) đảm bảo rằng văn bản được hiển thị theo đúng thứ tự (ví dụ: từ trái sang phải cho tiếng Anh, từ phải sang trái cho tiếng Ả Rập hoặc tiếng Do Thái), điều này rất quan trọng cho khả năng đọc.
    • SEO: Công cụ tìm kiếm sử dụng thuộc tính lang để xác định ngôn ngữ của trang, giúp cung cấp nội dung địa phương hóa phù hợp trong kết quả tìm kiếm.

    Bằng cách cập nhật các thuộc tính này một cách động khi locale thay đổi, bạn đảm bảo trải nghiệm nhất quán và dễ tiếp cận cho người dùng trên tất cả các ngôn ngữ được hỗ trợ.

    Triển khai Hook

    Tạo một hook tùy chỉnh để quản lý các thuộc tính HTML. Hook này lắng nghe sự thay đổi của locale và cập nhật các thuộc tính tương ứng:

    src/hooks/useI18nHTMLAttributes.tsx
    import { useEffect } from "react";import { useLocale } from "react-intlayer";import { getHTMLTextDir } from "intlayer";/** * Cập nhật các thuộc tính `lang` và `dir` của phần tử HTML <html> dựa trên locale hiện tại. * - `lang`: Thông báo cho trình duyệt và công cụ tìm kiếm về ngôn ngữ của trang. * - `dir`: Đảm bảo thứ tự đọc đúng (ví dụ: 'ltr' cho tiếng Anh, 'rtl' cho tiếng Ả Rập). * * Việc cập nhật động này rất cần thiết cho việc hiển thị văn bản chính xác, khả năng truy cập và SEO. */export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    // Cập nhật thuộc tính ngôn ngữ theo locale hiện tại.    document.documentElement.lang = locale;    // Đặt hướng văn bản dựa trên locale hiện tại.    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

    Sử dụng Hook trong Ứng dụng của Bạn

    Tích hợp hook vào thành phần chính của bạn để các thuộc tính HTML được cập nhật mỗi khi locale thay đổi:

    src/App.tsx
    import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";import "./App.css";const AppContent: FC = () => {  // Áp dụng hook để cập nhật thuộc tính lang và dir của thẻ <html> dựa trên locale.  useI18nHTMLAttributes();  // ... Phần còn lại của component của bạn};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

    Bằng cách áp dụng những thay đổi này, ứng dụng của bạn sẽ:

    • Đảm bảo thuộc tính ngôn ngữ (lang) phản ánh chính xác locale hiện tại, điều này quan trọng cho SEO và hành vi của trình duyệt.
    • Điều chỉnh hướng văn bản (dir) theo locale, nâng cao khả năng đọc và sử dụng cho các ngôn ngữ có thứ tự đọc khác nhau.
    • Cung cấp trải nghiệm dễ tiếp cận hơn, vì các công nghệ hỗ trợ phụ thuộc vào các thuộc tính này để hoạt động tối ưu.

    Cấu hình TypeScript

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

    Tự động hoàn thành

    Lỗi dịch thuật

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

    tsconfig.json
    {  // ... Các cấu hình TypeScript hiện có của bạn  "include": [    // ... Các cấu hình TypeScript 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:

    .gitignore
    # 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 của bạ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 các 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 Intlayer cho VS Code.

    Đi xa hơn

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

    Nhận thông báo về các bản phát hành sắp tới của Intlayer