Creation:2026-03-23Last update:2026-05-31

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

    ide.intlayer.org

    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ư i18next hay i18n.js, 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 Vite bằng cách cung cấp quản lý nội dung không phụ thuộc vào khung, hỗ trợ TypeScript 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 để thiết lập Intlayer trong ứng dụng Vite và Vanilla JS

    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 vanilla-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 để quản lý cấu hình, dịch thuật, khai báo nội dung, chuyển đổi mã nguồn và lệnh CLI.

      • vanilla-intlayer Gói tích hợp Intlayer với các ứng dụng JavaScript / TypeScript thuần túy. Nó cung cấp một pub/sub singleton (IntlayerClient) và các hàm hỗ trợ dựa trên callback (useIntlayer, useLocale, v.v.) để bất kỳ phần nào trong ứng dụng của bạn cũng có thể phản ứng với các thay đổi ngôn ngữ mà không phụ thuộc vào framework UI.

      • 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ữ ưa thích 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 tệp cấu hình để thiết lập 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 được bản địa 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 log Intlayer trong console, và nhiều hơn nữa. Để biết danh sách đầy đủ các tham số khả dụng, 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 { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [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à theo dõi 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ó cung cấp các alias để tối ưu hóa hiệu suất.

    4. Khởi tạo Intlayer trong entry point của bạn

      Gọi installIntlayer() trước khi bất kỳ nội dung nào được render để ngôn ngữ singleton toàn cầu sẵn sàng.

      src/main.ts
      import { installIntlayer } from "vanilla-intlayer";// Phải được gọi trước khi render bất kỳ nội dung i18n nào.installIntlayer();// Import và chạy các module ứng dụng của bạn.import "./app.js";

      Nếu bạn cũng sử dụng khai báo nội dung md() (Markdown), hãy cài đặt thêm trình render markdown:

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";installIntlayer();installIntlayerMarkdown();import "./app.js";

    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ữ các bản dịch:

      src/app.content.ts
      import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

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

    readTheDocs: t({
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Nhấp vào logo Vite để tìm hiểu thêm",
    }),
  },
} 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 miễn là chúng được bao gồm trong thư mục contentDir (mặc định là ./src) và khớp với phần mở rộng 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. Sử dụng Intlayer trong JavaScript của bạn

      vanilla-intlayer ánh xạ API của react-intlayer: useIntlayer(key, locale?) trả về nội dung đã dịch trực tiếp. Chuỗi hàm .onChange() vào kết quả để đăng ký theo dõi các thay đổi ngôn ngữ - tương đương với việc re-render trong React.

      src/main.ts
      import { installIntlayer, useIntlayer } from "vanilla-intlayer";installIntlayer();// Lấy nội dung ban đầu cho ngôn ngữ hiện tại.// Chuỗi hàm .onChange() để được thông báo mỗi khi ngôn ngữ thay đổi.const content = useIntlayer("app").onChange((newContent) => {  // Chỉ re-render hoặc cập nhật các node DOM bị ảnh hưởng  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(    newContent.title  );  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =    String(newContent.readTheDocs);});// Render lần đầudocument.querySelector<HTMLHeadingElement>("h1")!.textContent = String(  content.title);document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =  String(content.readTheDocs);

      Truy cập các giá trị lá dưới dạng chuỗi bằng cách bao bọc chúng trong String(), việc này sẽ gọi phương thức toString() của node và trả về văn bản đã dịch.

      Khi bạn cần giá trị cho một thuộc tính HTML thuần (ví dụ: alt, aria-label), hãy sử dụng trực tiếp .value:

      typescript
      img.alt = content.viteLogoLabel.value;

    7. Thay đổi ngôn ngữ nội dung của bạn

      Tùy chọn

      Để thay đổi ngôn ngữ nội dung, hãy sử dụng hàm setLocale được cung cấp bởi useLocale.

      src/locale-switcher.ts
      import { getLocaleName } from "intlayer";import { useLocale } from "vanilla-intlayer";export function setupLocaleSwitcher(container: HTMLElement): () => void {  const { locale, availableLocales, setLocale, subscribe } = useLocale();  const select = document.createElement("select");  select.setAttribute("aria-label", "Language");  const render = (currentLocale: string) => {    select.innerHTML = availableLocales      .map(        (loc) =>          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>            ${getLocaleName(loc)}          </option>`      )      .join("");  };  render(locale);  container.appendChild(select);  select.addEventListener("change", () => setLocale(select.value as any));  // Giữ dropdown đồng bộ khi ngôn ngữ thay đổi từ nơi khác  return subscribe((newLocale) => render(newLocale));}

    8. Render nội dung Markdown và HTML

      Tùy chọn

      Intlayer hỗ trợ khai báo nội dung dưới dạng md() và html(). Trong Vanilla JS, đầu ra đã biên dịch được chèn dưới dạng HTML thô qua innerHTML.

      Biên dịch và chèn HTML:

      src/main.ts
      import {  compileMarkdown,  installIntlayerMarkdown,  useIntlayer,} from "vanilla-intlayer";installIntlayerMarkdown();const content = useIntlayer("app").onChange((newContent) => {  const el = document.querySelector<HTMLDivElement>(".edit-note")!;  el.innerHTML = compileMarkdown(String(newContent.editNote));});document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =  compileMarkdown(String(content.editNote));
      TIP
      String(content.editNote) gọi toString() trên IntlayerNode để trả về chuỗi Markdown thô. Truyền nó vào compileMarkdown để lấy chuỗi HTML, sau đó thiết lập qua innerHTML.
      WARNING

      Chỉ sử dụng innerHTML với nội dung tin cậy. Nếu markdown đến từ đầu vào của người dùng, hãy lọc sạch nó trước (ví dụ với DOMPurify). Bạn có thể cài đặt trình render lọc sạch một cách linh hoạt:

      typescript
      import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";await installIntlayerMarkdownDynamic(async () => {  const DOMPurify = await import("dompurify");  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));});

    9. Thêm Localized Routing vào ứng dụng của bạn

      Tùy chọn

      Để tạo các route duy nhất cho mỗi ngôn ngữ (hữu ích cho SEO), bạn có thể sử dụng intlayerProxy trong cấu hình Vite của mình để phát hiện ngôn ngữ ở phía server.

      Đầu tiên, thêm intlayerProxy vào cấu hình Vite của bạn:

      Lưu ý rằng để sử dụng intlayerProxy trong môi trường production, bạn cần chuyển vite-intlayer từ devDependencies sang dependencies.
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // nên đặt đầu tiên
    intlayer(),
  ],
});

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

      Tùy chọn

      Để cập nhật URL trình duyệt khi ngôn ngữ thay đổi, hãy gọi useRewriteURL() sau khi cài đặt Intlayer:

      src/main.ts
      import { installIntlayer, useRewriteURL } from "vanilla-intlayer";installIntlayer();// Viết lại URL ngay lập tức và mỗi khi ngôn ngữ thay đổi sau đó.// Trả về một hàm hủy đăng ký để dọn dẹp.const stopRewriteURL = useRewriteURL();

    11. Chuyển đổi thuộc tính Language và Direction của HTML

      Tùy chọn

      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 nhằm hỗ trợ truy cập và SEO.

      src/main.ts
      import { getHTMLTextDir } from "intlayer";import { installIntlayer, useLocale } from "vanilla-intlayer";installIntlayer();useLocale({  onLocaleChange: (locale) => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  },});

    12. Lazy-load từ điển theo ngôn ngữ

      Tùy chọn

      Đối với các ứng dụng lớn, bạn có thể muốn chia từ điển của mỗi ngôn ngữ thành một phần (chunk) riêng. Sử dụng useDictionaryDynamic cùng với import() động của Vite:

      src/app.ts
      import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";installIntlayer();const unsubscribe = useDictionaryDynamic(  {    en: () => import("../.intlayer/dictionaries/en/app.mjs"),    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),    es: () => import("../.intlayer/dictionaries/es/app.mjs"),  },  "app").onChange((content) => {  document.querySelector("h1")!.textContent = String(content.title);});
      Mỗi bundle ngôn ngữ chỉ được tải khi ngôn ngữ đó được kích hoạt và kết quả được lưu vào cache - các lần chuyển đổi sau đó sang cùng một ngôn ngữ sẽ diễn ra tức thì.

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

      Tùy chọn

      Nếu bạn có một codebase hiện có, việc chuyển đổi hàng ngàn tệp có thể tốn thời gian.

      Để giảm bớt quá 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 và trích xuất nội dung.

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

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Cấu hình còn lại của bạn  compiler: {    /**     * Chỉ định xem trình biên dịch có nên được bật hay không.     */    enabled: true,    /**     * Định nghĩa đường dẫn các tệp đầu ra     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Chỉ định xem các thành phần có nên được lưu lại sau khi được chuyển đổi hay không.     * Bằng cách đó, trình biên dịch có thể chỉ chạy một lần để chuyển đổi ứng dụng, và sau đó nó có thể được gỡ bỏ.     */    saveComponents: false,    /**     * Tiền tố phím 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

    (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.

    Cấu hình TypeScript

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

    tsconfig.json
    {  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

    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 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 chỉ dẫn sau vào tệp .gitignore của mình:

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

    Extension 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 Extension Intlayer VS Code chính thức.

    Cài đặt từ VS Code Marketplace

    Extension 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 theo thời gian thực cho các bản dịch bị thiếu.
    • Xem trước nội dung đã dịch trực tiếp.
    • Quick actions để 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 extension, hãy tham khảo tài liệu Extension Intlayer VS Code.

    Đi xa hơn

    Để tìm hiểu sâu hơn, bạn có thể triển khai trình soạn thảo trực quan hoặc bên ngoài hóa nội dung của bạn bằng CMS.

    Vite và Preact
    Vite và Lit