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

    Dịch trang web Vite và Svelte 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ư svelte-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 Svelte bằng cách cung cấp phạm vi nội dung cấp thành phần, bản dịch phản ứng 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à Svelte

    ide.intlayer.org

    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 svelte-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 lại, và các lệnh CLI.

      • svelte-intlayer Gói tích hợp Intlayer với ứng dụng Svelte. Nó cung cấp các context providers và hooks cho việc quốc tế hóa trong Svelte.

      • 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 để 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 file cấu hình này, bạn có thể thiết lập các URL có đị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. 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 { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), intlayer()],});
      Plugin intlayer() của Vite đượ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ó cung cấp các alias để tối ưu hiệu năng.

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

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

const appContent = {
  key: "app",
  content: {
    title: t({
      en: "Hello World",
      fr: "Bonjour le monde",
      es: "Hola mundo",
    }),
  },
} 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ù hợ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, tham khảo tài liệu khai báo nội dung.

    5. Sử dụng Intlayer trong mã của bạn

      src/App.svelte
      <script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- Hiển thị nội dung như nội dung đơn giản --><h1>{$content.title}</h1><!-- Để hiển thị nội dung có thể chỉnh sửa bằng trình soạn thảo --><h1>{@const Title = $content.title}<Title /></h1><!-- Để hiển thị nội dung dưới dạng chuỗi --><div aria-label={$content.title.value}></div><div aria-label={$content.title.toString()}></div><div aria-label={String($content.title)}></div>> Nếu ứng dụng của bạn đã tồn tại, bạn có thể sử dụng [Intlayer Compiler](/vi/doc/compiler) kết hợp với [lệnh extract](/vi/doc/concept/cli/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
      src/App.svelte
      <script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from "svelte-intlayer";// Lấy thông tin locale và hàm setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Xử lý thay đổi localeconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  setLocale(newLocale);};</script><div>  <select value={$locale} on:change={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

    7. Hiển thị Markdown

      Tùy chọn

      Intlayer hỗ trợ hiển thị nội dung Markdown trực tiếp trong ứng dụng Svelte của bạn. Theo mặc định, Markdown được xử lý như văn bản thuần túy. Để chuyển đổi Markdown thành HTML phong phú, bạn có thể tích hợp @humanspeak/svelte-markdown hoặc một trình phân tích markdown khác.

      Để xem cách khai báo nội dung markdown sử dụng gói intlayer, xem tài liệu markdown doc.
      src/App.svelte
      <script>  import { setIntlayerMarkdown } from "svelte-intlayer";  setIntlayerMarkdown((markdown) =>   // hiển thị nội dung markdown dưới dạng chuỗi   return markdown;  );</script><h1>{$content.markdownContent}</h1>
      Bạn cũng có thể truy cập dữ liệu front-matter của markdown bằng cách sử dụng thuộc tính content.markdownContent.metadata.xxx.

    8. Thiết lập trình chỉnh sửa intlayer / CMS

      Tùy chọn

      Để thiết lập trình chỉnh sửa intlayer, bạn phải làm theo tài liệu trình chỉnh sửa intlayer.

      Để thiết lập CMS intlayer, bạn phải làm theo tài liệu CMS intlayer.

    9. Thêm định tuyến có bản địa hóa vào ứng dụng của bạn

      Tùy chọn

      Để xử lý định tuyến có bản địa hóa trong ứng dụng Svelte của bạn, bạn có thể sử dụng svelte-spa-router cùng với localeFlatMap của Intlayer để tạo các tuyến đường cho từng ngôn ngữ.

      Trước tiên, cài đặt svelte-spa-router:

      bash
      npm install svelte-spa-routernpx intlayer init

      Sau đó, tạo một file Router.svelte để định nghĩa các tuyến đường của bạn:

      src/Router.svelte
      <script lang="ts">import { localeFlatMap } from "intlayer";import Router from "svelte-spa-router";import { wrap } from "svelte-spa-router/wrap";import App from "./App.svelte";const routes = Object.fromEntries(    localeFlatMap(({locale, urlPrefix}) => [    [        urlPrefix || '/',        wrap({            component: App as any,            props: {                locale,            },        }),    ],    ]));</script><Router {routes} />

      Cập nhật file main.ts của bạn để mount component Router thay vì App:

      src/main.ts
      import { mount } from "svelte";import Router from "./Router.svelte";const app = mount(Router, {  target: document.getElementById("app")!,});export default app;

      Cuối cùng, cập nhật App.svelte của bạn để nhận prop locale và sử dụng nó với useIntlayer:

      src/App.svelte
      <script lang="ts">import type { Locale } from 'intlayer';import { useIntlayer } from "svelte-intlayer";import Counter from './lib/Counter.svelte';import LocaleSwitcher từ './lib/LocaleSwitcher.svelte';export let locale: Locale;$: content = useIntlayer('app', locale);</script><main>  <div class="locale-switcher-container">    <LocaleSwitcher currentLocale={locale} />  </div>  <!-- ... phần còn lại của ứng dụng của bạn ... --></main>

      Cấu hình Routing phía Server (Tùy chọn)

      Song song với đó, bạn cũng có thể sử dụng intlayerProxy để thêm routing phía server cho ứng dụng của bạn. Plugin này sẽ tự động phát hiện locale hiện tại dựa trên URL và thiết lập cookie locale phù hợp. Nếu không có locale nào được chỉ định, plugin sẽ xác định locale phù hợp nhất dựa trên sở thích ngôn ngữ trình duyệt của người dùng. Nếu không phát hiện được locale nào, nó sẽ chuyển hướng đến locale mặc định.

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

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    intlayerProxy(), // should be placed first
    svelte(),
    intlayer(),
  ],
});

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

      Tùy chọn

      Để cho phép người dùng chuyển đổi ngôn ngữ và cập nhật URL tương ứng, bạn có thể tạo một component LocaleSwitcher. Component này sẽ sử dụng getLocalizedUrl từ intlayer và push từ svelte-spa-router.

      src/lib/LocaleSwitcher.svelte
      <script lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";import { push } from "svelte-spa-router";export let currentLocale: string | undefined = undefined;// Lấy thông tin ngôn ngữconst { locale, availableLocales } = useLocale();// Xử lý thay đổi ngôn ngữconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  const currentUrl = window.location.pathname;  const url = getLocalizedUrl( currentUrl, newLocale);  push(url);};</script><div class="locale-switcher">  <select value={currentLocale ?? $locale} onchange={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

    11. 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 Git

    Khuyến nghị nên bỏ qua các file được tạo ra 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 chỉ dẫn sau vào file .gitignore của bạn:

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

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

    Để cải thiện trải nghiệm phát triể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

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

    Tiến xa hơn

    Để tiến xa hơn, bạn có thể triển khai trình chỉnh sửa 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.

    Vite và Solid
    SvelteKit