Creation:2025-04-18Last update:2026-05-31

    Dịch trang web Vite và Preact của bạn bằng Intlayer | Quốc tế hóa (i18n)

    www.youtube.com

    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ư preact-i18n 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ư:

    Intlayer được tối ưu hóa để hoạt động hoàn hảo với Preact bằng cách cung cấp phạm vi nội dung cấp thành phần, bản dịch được tải từng phần và tất cả các tính năng cần thiết để mở rộng quy mô quốc tế hóa (i18n).

    Thay vì tải các tệp JSON lớn vào trang của bạn, hãy chỉ tải nội dung cần thiết. Intlayer giúp giảm tới 50% kích thước bundle và kích thước trang.

    Xác định phạm vi nội dung ứng dụng của bạn tạo điều kiện bảo trì cho các ứng dụng quy mô lớn. Bạn có thể sao chép hoặc xóa một thư mục tính năng mà không phải lo lắng về việc xem lại toàn bộ cơ sở mã nội dung của mình. Ngoài ra, Intlayer được nhập đầy đủ để đảm bảo tính chính xác cho nội dung của bạn.

    Nội dung cùng định vị giảm ngữ cảnh cần thiết của Mô hình ngôn ngữ lớn (LLM). Intlayer cũng đi kèm một bộ công cụ, chẳng hạn như CLI để kiểm tra các bản dịch bị thiếu,LSP, MCP và agent Skills, để giúp trải nghiệm của nhà phát triển (DX) trở nên mượt mà hơn nữa đối với các tác nhân AI.

    Sử dụng tính năng tự động hóa để dịch trong quy trình CI/CD của bạn bằng cách sử dụng LLM mà bạn chọn với chi phí do nhà cung cấp AI của bạn chi trả. Intlayer cũng cung cấp trình biên dịch để tự động trích xuất nội dung cũng như nền tảng web để giúp dịch ở chế độ nền.

    Việc kết nối các tệp JSON lớn với các thành phần có thể dẫn đến các vấn đề về hiệu suất và khả năng phản hồi. Intlayer tối ưu hóa việc tải nội dung của bạn tại thời điểm build.

    Không chỉ là giải pháp i18n, Intlayer còn cung cấp trình chỉnh sửa trực quan và CMS đầy đủ để giúp bạn quản lý nội dung đa ngôn ngữ của mình trong thời gian thực, giúp việc cộng tác với người dịch, người viết quảng cáo và các thành viên khác trong nhóm trở nên liền mạch. Nội dung có thể được lưu trữ cục bộ và/hoặc từ xa.

    Hướng Dẫn Từng Bước Để Cài Đặt Intlayer Trong Ứng Dụng Vite và Preact

    Xem Mẫu Ứng Dụng trên GitHub.

    1. Cài Đặt Các Phụ Thuộc

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

      bash
      npm install intlayer preact-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 và lệnh CLI.

      • preact-intlayer

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

      • vite-intlayer

        Bao gồm plugin Vite để tích hợp Intlayer với Vite bundler, 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. 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ữ của ứ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,
  },
  routing: {
    mode: "prefix-no-default", // Mặc định: thêm tiền tố cho tất cả các ngôn ngữ ngoại trừ ngôn ngữ mặc định
    storage: ["cookie", "header"], // Mặc định: lưu ngôn ngữ trong cookie và phát hiện từ header
  },
};

export default config;
      Thông qua tệp cấu hình này, bạn có thể thiết lập URL đa ngôn ngữ, chế độ định tuyến, tùy chọn lưu trữ, 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. 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
      import { defineConfig } from "vite";
import preact from "@preact/preset-vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [preact(), 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 file 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 bí danh để tối ưu hiệu suất.

    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 type { ComponentChildren } from "preact";

const appContent = {
  key: "app",
  content: {
    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    preactLogo: t({
      en: "Preact logo",
      fr: "Logo Preact",
      es: "Logo Preact",
    }),

    title: "Vite + Preact",

    count: t({
      en: "count is ",
      fr: "le compte est ",
      es: "el recuento es ",
    }),

    edit: t<ComponentChildren>({
      en: (
        <>
          Edit <code>src/app.tsx</code> and save to test HMR
        </>
      ),
      fr: (
        <>
          Éditez <code>src/app.tsx</code> et enregistrez pour tester HMR
        </>
      ),
      es: (
        <>
          Edita <code>src/app.tsx</code> y guarda para probar HMR
        </>
      ),
    }),

    readTheDocs: t({
      en: "Click on the Vite and Preact logos to learn more",
      fr: "Cliquez sur les logos Vite et Preact pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Preact para obtener más información",
    }),
  },
} 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 phù hợp với phần mở rộng của file khai báo nội dung (mặc định là .content.{json,ts,tsx,js,jsx,mjs,cjs}).
      Để biết thêm chi tiết, hãy tham khảo tài liệu khai báo nội dung.
      Nếu file nội dung của bạn bao gồm mã TSX, bạn có thể cần import import { h } from "preact"; hoặc đảm bảo pragma JSX của bạn được thiết lập đúng cho Preact.

    5. Sử dụng Intlayer trong Code của Bạn

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

      src/app.tsx
      import { useState } from "preact/hooks";
import type { FunctionalComponent } from "preact";
import preactLogo from "./assets/preact.svg"; // Giả sử bạn có file preact.svg
import viteLogo from "/vite.svg";
import "./app.css"; // Giả sử file CSS của bạn tên là app.css
import { IntlayerProvider, useIntlayer } from "preact-intlayer";

const AppContent: FunctionalComponent = () => {
  const [count, setCount] = useState(0);
  const content = useIntlayer("app");

  return (
    <>
      <div>
        <a href="https://vitejs.dev" target="_blank">
          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
        </a>
        <a href="https://preactjs.com" target="_blank">
          <img
            src={preactLogo}
            class="logo preact"
            alt={content.preactLogo.value}
          />
        </a>
      </div>
      <h1>{content.title}</h1>
      <div class="card">
        <button onClick={() => setCount((count) => count + 1)}>
          {content.count}
          {count}
        </button>
        <p>{content.edit}</p>
      </div>
      {/* Nội dung Markdown */}
      <div>{content.myMarkdownContent}</div>

      {/* Nội dung HTML */}
      <div>{content.myHtmlContent}</div>

      <p class="read-the-docs">{content.readTheDocs}</p>
    </>
  );
};

const App: FunctionalComponent = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;
      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ụ:
      html
      <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)}" />
      Lưu ý: Trong Preact, className thường được viết là class.
      Để tìm hiểu thêm về hook useIntlayer, hãy tham khảo tài liệu (API tương tự cho preact-intlayer).
      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.

    6. Thay đổi ngôn ngữ của nội dung

      Tùy chọn

      Để 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 type { FunctionalComponent } from "preact";
import { Locales } from "intlayer";
import { useLocale } from "preact-intlayer";

const LocaleSwitcher: FunctionalComponent = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.ENGLISH)}>
      Thay đổi ngôn ngữ sang tiếng Anh
    </button>
  );
};

export default LocaleSwitcher;
      Để tìm hiểu thêm về hook useLocale, hãy tham khảo tài liệu (API tương tự cho preact-intlayer).

    7. Thêm định tuyến cục bộ vào ứng dụng của bạn

      Tùy chọn

      Mục đích của bước này là tạo các route 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ụ:

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

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

      src/components/LocaleRouter.tsx
      import { localeMap } from "intlayer";
import { IntlayerProvider } from "preact-intlayer";
import { LocationProvider, Router, Route } from "preact-iso";
import type { ComponentChildren, FunctionalComponent } from "preact";

/**
 * Một thành phần định tuyến thiết lập các tuyến đường cụ thể cho từng ngôn ngữ.
 * Nó sử dụng preact-iso để quản lý điều hướng và hiển thị các thành phần cục bộ.
 */
export const LocaleRouter: FunctionalComponent<{
  children: ComponentChildren;
}> = ({ children }) => (
  <LocationProvider>
    <Router>
      {localeMap(({ locale, urlPrefix }) => ({ locale, urlPrefix }))
        .sort((a, b) => b.urlPrefix.length - a.urlPrefix.length)
        .map(({ locale, urlPrefix }) => (
          <Route
            key={locale}
            path={`${urlPrefix}/:rest*`}
            component={() => (
              <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
            )}
          />
        ))}
    </Router>
  </LocationProvider>
);

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

      src/app.tsx
      import { LocaleRouter } from "./components/LocaleRouter";
import type { FunctionalComponent } from "preact";

// ... Thành phần AppContent của bạn

const App: FunctionalComponent = () => (
  <LocaleRouter>
    <AppContent />
  </LocaleRouter>
);

export default App;

    8. Thay đổi URL khi ngôn ngữ thay đổi

      Tùy chọn

      Để thay đổi URL khi ngôn ngữ thay đổi, bạn có thể sử dụng thuộc tính onLocaleChange được cung cấp bởi hook useLocale. Đồng thời, bạn có thể sử dụng phương thức route từ useLocation của preact-iso để cập nhật đường dẫn URL.

      src/components/LocaleSwitcher.tsx
      import { useLocation } from "preact-iso";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "preact-intlayer";
import type { FunctionalComponent } from "preact";

const LocaleSwitcher: FunctionalComponent = () => {
  const { url, route } = useLocation();
  const { locale, availableLocales, setLocale } = useLocale({
    onLocaleChange: (newLocale) => {
      // Xây dựng URL với ngôn ngữ đã cập nhật
      // Ví dụ: /es/about?foo=bar
      const pathWithLocale = getLocalizedUrl(url, newLocale);

      // Cập nhật đường dẫn URL
      route(pathWithLocale, true); // true để thay thế (replace)
    },
  });

  return (
    <div>
      <button popovertarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <a
            href={getLocalizedUrl(url, localeItem)}
            hreflang={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={(e) => {
              e.preventDefault();
              setLocale(localeItem);
              // Điều hướng theo lập trình sau khi thiết lập ngôn ngữ sẽ được xử lý bởi onLocaleChange
            }}
            key={localeItem}
          >
            <span>
              {/* Locale - ví dụ: FR */}
              {localeItem}
            </span>
            <span>
              {/* Ngôn ngữ trong chính Locale đó - ví dụ: Français */}
              {getLocaleName(localeItem, localeItem)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Ngôn ngữ trong Locale hiện tại - ví dụ: Francés với ngôn ngữ hiện tại được đặt thành Locales.SPANISH */}
              {getLocaleName(localeItem, locale)}
            </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>
  );
};

export default LocaleSwitcher;

      Tham khảo tài liệu:

      - Hook useLocale (API tương tự cho preact-intlayer)> - Hook getLocaleName> - Hook getLocalizedUrl> - Hook getHTMLTextDir> - Thuộc tính hreflang> - Thuộc tính lang> - Thuộc tính dir> - Thuộc tính aria-current> - Popover API

    9. Chuyển đổi thuộc tính ngôn ngữ và hướng của HTML

      Tùy chọn

      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 lang và dir của thẻ <html> để khớp với ngôn ngữ hiện tại là rất quan trọng. Làm như vậ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 trên 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 văn bản được hiển thị theo thứ tự thích hợp (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 cần thiết cho khả năng đọc.
      • SEO: Các công cụ tìm kiếm sử dụng thuộc tính lang để xác định ngôn ngữ của trang của bạn, giúp phục vụ nội dung được bản địa 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 linh hoạt khi ngôn ngữ 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 các thay đổi về ngôn ngữ và cập nhật các thuộc tính cho phù hợp:

      src/hooks/useI18nHTMLAttributes.tsx
      import { useEffect } from "preact/hooks";
import { useLocale } from "preact-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 ngôn ngữ 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 chính xác (ví dụ: 'ltr' cho tiếng Anh, 'rtl' cho tiếng Ả Rập).
 *
 * Bản cập nhật động này rất cần thiết để hiển thị văn bản, khả năng truy cập và SEO thích hợp.
 */
export const useI18nHTMLAttributes = () => {
  const { locale } = useLocale();

  useEffect(() => {
    // Cập nhật thuộc tính ngôn ngữ thành ngôn ngữ hiện tại.
    document.documentElement.lang = locale;

    // Đặt hướng văn bản dựa trên ngôn ngữ 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ập nhật bất cứ khi nào ngôn ngữ thay đổi:

      src/app.tsx
      import type { FunctionalComponent } from "preact";
import { IntlayerProvider } from "preact-intlayer"; // useIntlayer đã được nhập nếu AppContent cần nó
import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
import "./app.css";
// Định nghĩa AppContent từ Bước 5

const AppWithHooks: FunctionalComponent = () => {
  // Áp dụng hook để cập nhật các thuộc tính lang và dir của thẻ <html> dựa trên ngôn ngữ.
  useI18nHTMLAttributes();

  // Giả sử AppContent là thành phần hiển thị nội dung chính của bạn từ Bước 5
  return <AppContent />;
};

const App: FunctionalComponent = () => (
  <IntlayerProvider>
    <AppWithHooks />
  </IntlayerProvider>
);

export default App;

    10. Tạo thành phần liên kết cục bộ

      Tùy chọn

      Để đảm bảo rằng điều hướng của ứng dụng của bạn tôn trọng ngôn ngữ hiện tại, bạn có thể tạo một thành phần Link tùy chỉnh. Thành phần này tự động thêm tiền tố ngôn ngữ hiện tại vào các URL nội bộ.

      Hành vi này hữu ích vì một số lý do:

      • SEO và Trải nghiệm người dùng: URL được bản địa hóa giúp công cụ tìm kiếm lập chỉ mục các trang dành riêng cho ngôn ngữ một cách chính xác và cung cấp cho người dùng nội dung bằng ngôn ngữ ưa thích của họ.
      • Tính nhất quán: Bằng cách sử dụng một liên kết được bản địa hóa trong toàn bộ ứng dụng của mình, bạn đảm bảo rằng điều hướng vẫn nằm trong ngôn ngữ hiện tại, ngăn chặn các thay đổi ngôn ngữ không mong muốn.
      • Khả năng bảo trì: Việc tập trung logic bản địa hóa trong một thành phần duy nhất giúp đơn giản hóa việc quản lý các URL.

      Dưới đây là cách triển khai thành phần Link được bản địa hóa trong Preact:

      src/components/Link.tsx
      import { getLocalizedUrl } from "intlayer";
import { useLocale } from "preact-intlayer";
import { forwardRef } from "preact/compat";
import type { JSX } from "preact";

export interface LinkProps extends JSX.HTMLAttributes<HTMLAnchorElement> {
  href: string;
}

/**
 * Hàm tiện ích để kiểm tra xem một URL nhất định có phải là bên ngoài hay không.
 * Nếu URL bắt đầu bằng http:// hoặc https://, nó được coi là bên ngoài.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * Một thành phần Link tùy chỉnh thích ứng với thuộc tính href dựa trên ngôn ngữ hiện tại.
 * Đối với các liên kết nội bộ, nó sử dụng `getLocalizedUrl` để thêm tiền tố ngôn ngữ vào URL (ví dụ: /fr/about).
 * Điều này đảm bảo rằng điều hướng vẫn nằm trong cùng một bối cảnh ngôn ngữ.
 */
export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
  ({ href, children, ...props }, ref) => {
    const { locale } = useLocale();
    const isExternalLink = checkIsExternalLink(href);

    // Nếu liên kết là nội bộ và một href hợp lệ được cung cấp, hãy lấy URL được bản địa hóa.
    const hrefI18n =
      href && !isExternalLink ? getLocalizedUrl(href, locale) : href;

    return (
      <a href={hrefI18n} ref={ref} {...props}>
        {children}
      </a>
    );
  }
);

Link.displayName = "Link";

      Cách hoạt động

      • Phát hiện liên kết bên ngoài:
        Hàm trợ giúp checkIsExternalLink xác định xem một URL có phải là bên ngoài hay không. Các liên kết bên ngoài được để nguyên vì chúng không cần bản địa hóa.
      • Truy xuất ngôn ngữ hiện tại:
        Hook useLocale cung cấp ngôn ngữ hiện tại (ví dụ: fr cho tiếng Pháp).
      • Bản địa hóa URL:
        Đối với các liên kết nội bộ (tức là không phải bên ngoài), getLocalizedUrl được sử dụng để tự động thêm tiền tố ngôn ngữ hiện tại vào URL. Điều này có nghĩa là nếu người dùng của bạn đang ở tiếng Pháp, việc vượt qua /about làm href sẽ chuyển nó thành /fr/about.
      • Trả về liên kết:
        Thành phần trả về phần tử <a> với URL được bản địa hóa, đảm bảo điều hướng nhất quán với ngôn ngữ.

    11. Hiển thị Markdown và HTML

      Tùy chọn

      Intlayer hỗ trợ hiển thị nội dung Markdown và HTML trong Preact.

      Bạn có thể tùy chỉnh việc hiển thị nội dung Markdown và HTML bằng cách sử dụng phương thức .use(). Phương thức này cho phép bạn ghi đè việc hiển thị mặc định của các thẻ cụ thể.

      tsx
      import { useIntlayer } from "preact-intlayer";const { myMarkdownContent, myHtmlContent } = useIntlayer("my-component");// ...return (  <div>    {/* Hiển thị cơ bản */}    {myMarkdownContent}    {/* Hiển thị tùy chỉnh cho Markdown */}    {myMarkdownContent.use({      h1: (props) => <h1 style={{ color: "red" }} {...props} />,    })}    {/* Hiển thị cơ bản cho HTML */}    {myHtmlContent}    {/* Hiển thị tùy chỉnh cho HTML */}    {myHtmlContent.use({      b: (props) => <strong style={{ color: "blue" }} {...props} />,    })}  </div>);

    12. 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
      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;

      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
      npx intlayer extract

    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.

    Autocompletion

    Translation error

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

    tsconfig.json
    {  // ... Các cấu hình TypeScript hiện có của bạn  "compilerOptions": {    // ...    "jsx": "react-jsx",    "jsxImportSource": "preact", // Được đề xuất cho Preact 10+    // ...  },  "include": [    // ... Các cấu hình TypeScript hiện có của bạn    ".intlayer/**/*.ts", // Bao gồm các loại được tạo tự động  ],}
    Đảm bảo tsconfig.json của bạn được thiết lập cho Preact, đặc biệt là jsx và jsxImportSource hoặc jsxFactory/jsxFragmentFactory cho các phiên bản Preact cũ hơn nếu không sử dụng mặc định của preset-vite.

    Cấu hình Git

    Bạn nên bỏ qua các tệp do Intlayer tạo ra. Điều này cho phép bạn tránh commit chúng vào kho lưu trữ 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 mình:

    bash
    #  Bỏ qua các tệp do Intlayer tạo ra.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 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 theo thời gian thực cho các bản dịch còn thiếu.
    • Xem trước nội tuyến nội dung đã dịch.
    • 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 Intlayer VS Code.

    (Tuỳ chọn) Sitemap và robots.txt (sinh lúc build)

    Intlayer cung cấp generateSitemap và getMultilingualUrls để định dạng sitemap.xml đa ngôn ngữ và robots.txt cho crawler rồi tự ghi vào public/. Thường chạy một script Node nhỏ trước Vite (ví dụ hook npm predev / prebuild).

    Sitemap

    Trình tạo sitemap của Intlayer tôn trọng cấu hình locale và thêm metadata cho crawler.

    Sitemap hỗ trợ không gian tên xhtml:link (hreflang). Thay vì chỉ liệt kê URL phẳng, Intlayer nối hai chiều mọi bản địa phương của từng trang (ví dụ /about, /fr/about hoặc /about?lang=fr tùy chế độ routing).

    Robots.txt

    Dùng getMultilingualUrls để quy tắc Disallow áp dụng cho mọi biến thể URL của đường dẫn nhạy cảm.

    1. Thêm generate-seo.mjs ở thư mục gốc dự án

    generate-seo.mjs
    import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

    Cần cài intlayer để script import. Môi trường production đặt SITE_URL (ví dụ trong CI).

    Nên dùng generate-seo.mjs cho ESM của Node. Nếu dùng generate-seo.js, đặt "type": "module" trong package.json hoặc bật ESM tương đương.

    2. Chạy script trước Vite

    package.json
    {  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

    Chỉnh lệnh nếu dùng pnpm hoặc yarn. Có thể gọi từ CI hoặc bước pipeline khác.

    Đ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 bên ngoài hóa nội dung của bạn bằng CMS.

    SvelteKit
    Vite và Vanilla JS