Creation:2025-11-20Last update:2026-05-31

    Dịch trang web SvelteKit 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 SvelteKit bằng cách cung cấp định tuyến đa ngôn ngữ, hỗ trợ SSR 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 SvelteKit

    Để bắt đầu, hãy tạo một dự án SvelteKit mới. Dưới đây là cấu trúc cuối cùng mà chúng ta sẽ tạo:

    bash
    .├── intlayer.config.ts├── package.json├── src│   ├── app.d.ts│   ├── app.html│   ├── hooks.server.ts│   ├── lib│   │   ├── getLocale.ts│   │   ├── LocaleSwitcher.svelte│   │   └── LocalizedLink.svelte│   ├── params│   │   └── locale.ts│   └── routes│       ├── [[locale=locale]]│       │   ├── +layout.svelte│       │   ├── +layout.ts│       │   ├── +page.svelte│       │   ├── +page.ts│       │   ├── about│       │   │   ├── +page.svelte│       │   │   ├── +page.ts│       │   │   └── page.content.ts│       │   ├── Counter.content.ts│       │   ├── Counter.svelte│       │   ├── Header.content.ts│       │   ├── Header.svelte│       │   ├── home.content.ts│       │   └── layout.content.ts│       ├── +layout.svelte│       └── layout.css├── static│   ├── favicon.svg│   └── robots.txt├── svelte.config.js├── tsconfig.json└── vite.config.ts

    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 i18n cốt lõi.
      • svelte-intlayer: Cung cấp các context provider và store cho Svelte/SvelteKit.
      • vite-intlayer: Plugin Vite để tích hợp khai báo nội dung với quá trình build.

    2. Cấu hình dự án của bạn

      Tạo một file cấu hình trong thư mục gốc của dự án:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },};export default config;

    3. Tích hợp Intlayer vào cấu hình Vite của bạn

      Cập nhật vite.config.ts của bạn để bao gồm plugin Intlayer. Plugin này xử lý việc transpile các file nội dung của bạn.

      vite.config.ts
      import { sveltekit } from "@sveltejs/kit/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer(), sveltekit()], // thứ tự quan trọng, Intlayer nên được đặt trước SvelteKit});

    4. Khai báo Nội dung của bạn

      Tạo các file khai báo nội dung ở bất kỳ đâu trong thư mục src của bạn (ví dụ: src/lib/content hoặc cùng thư mục với các component của bạn). Các file này định nghĩa nội dung có thể dịch cho ứng dụng của bạn bằng cách sử dụng hàm t() cho từng locale.

    5. Sử dụng Intlayer trong các Component của bạn

      Bây giờ bạn có thể sử dụng hàm useIntlayer trong bất kỳ component Svelte nào. Hàm này trả về một store phản ứng tự động cập nhật khi locale thay đổi. Hàm sẽ tự động tuân theo locale hiện tại (cả trong SSR và điều hướng phía client).

      Lưu ý: useIntlayer trả về một store của Svelte, vì vậy bạn cần sử dụng tiền tố `--- createdAt: 2025-11-20 updatedAt: 2026-05-31 title: Cách dịch ứng dụng SvelteKit của bạn – hướng dẫn i18n 2026 description: Khám phá cách làm cho trang web SvelteKit của bạn đa ngôn ngữ. Theo dõi tài liệu để quốc tế hóa (i18n) và dịch nó bằng cách sử dụng Server-Side Rendering (SSR). keywords:

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

    Mục lục

    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. Nó hoạt động liền mạch với khả năng Server-Side Rendering (SSR) của SvelteKit.

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

    • Dễ dàng quản lý bản dịch bằng cách sử dụng các từ điển khai báo ở cấp độ component.
    • Định vị hóa động metadata, các route và nội dung.
    • Đảm bảo hỗ trợ TypeScript với các kiểu được tạo tự động.
    • Tận dụng SSR của SvelteKit để quốc tế hóa thân thiện với SEO.

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

    Để bắt đầu, hãy tạo một dự án SvelteKit mới. Dưới đây là cấu trúc cuối cùng mà chúng ta sẽ tạo:

    bash
    .├── intlayer.config.ts├── package.json├── src│   ├── app.d.ts│   ├── app.html│   ├── hooks.server.ts│   ├── lib│   │   ├── getLocale.ts│   │   ├── LocaleSwitcher.svelte│   │   └── LocalizedLink.svelte│   ├── params│   │   └── locale.ts│   └── routes│       ├── [[locale=locale]]│       │   ├── +layout.svelte│       │   ├── +layout.ts│       │   ├── +page.svelte│       │   ├── +page.ts│       │   ├── about│       │   │   ├── +page.svelte│       │   │   ├── +page.ts│       │   │   └── page.content.ts│       │   ├── Counter.content.ts│       │   ├── Counter.svelte│       │   ├── Header.content.ts│       │   ├── Header.svelte│       │   ├── home.content.ts│       │   └── layout.content.ts│       ├── +layout.svelte│       └── layout.css├── static│   ├── favicon.svg│   └── robots.txt├── svelte.config.js├── tsconfig.json└── vite.config.ts

    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 i18n cốt lõi.
      • svelte-intlayer: Cung cấp các context provider và store cho Svelte/SvelteKit.
      • vite-intlayer: Plugin Vite để tích hợp khai báo nội dung với quá trình build.

    2. Cấu hình dự án của bạn

      Tạo một file cấu hình trong thư mục gốc của dự án:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },};export default config;

    3. Tích hợp Intlayer vào cấu hình Vite của bạn

      Cập nhật vite.config.ts của bạn để bao gồm plugin Intlayer. Plugin này xử lý việc transpile các file nội dung của bạn.

      vite.config.ts
      import { sveltekit } from "@sveltejs/kit/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer(), sveltekit()], // thứ tự quan trọng, Intlayer nên được đặt trước SvelteKit});

    4. Khai báo Nội dung của bạn

      Tạo các file khai báo nội dung ở bất kỳ đâu trong thư mục src của bạn (ví dụ: src/lib/content hoặc cùng thư mục với các component của bạn). Các file này định nghĩa nội dung có thể dịch cho ứng dụng của bạn bằng cách sử dụng hàm t() cho từng locale.

    5. Sử dụng Intlayer trong các Component của bạn

      để truy cập giá trị phản ứng của nó (ví dụ: $content.title).

      src/lib/components/Component.svelte
      <script lang="ts">  import { useIntlayer } from "svelte-intlayer";  // "hero-section" tương ứng với key đã định nghĩa ở Bước 4  const content = useIntlayer("hero-section");</script><!-- Hiển thị nội dung dưới dạng 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><!-- Để render 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>

    6. Thiết lập routing

      Tùy chọn

      Các bước sau đây hướng dẫn cách thiết lập routing dựa trên locale trong SvelteKit. Điều này cho phép URL của bạn bao gồm tiền tố locale (ví dụ: /en/about, /fr/about) để cải thiện SEO và trải nghiệm người dùng.

      bash
      .└─── src    ├── app.d.ts                  # Định nghĩa kiểu locale    ├── hooks.server.ts           # Quản lý routing theo locale    ├── lib    │   └── getLocale.ts          # Kiểm tra locale từ header, cookies    ├── params    │   └── locale.ts             # Định nghĩa tham số locale    └── routes        ├── [[locale=locale]]     # Bao bọc trong nhóm route để đặt locale        │   ├── +layout.svelte    # Bố cục cục bộ cho route        │   ├── +layout.ts        │   ├── +page.svelte        │   ├── +page.ts        │   └── about        │       ├── +page.svelte        │       └── +page.ts        └── +layout.svelte         # Bố cục gốc cho font chữ và kiểu toàn cục

    7. Xử lý phát hiện locale phía Server

      Trong SvelteKit, server cần biết locale của người dùng để render nội dung chính xác trong SSR. Chúng ta sử dụng hooks.server.ts để phát hiện locale từ URL hoặc cookies.

      Tạo hoặc chỉnh sửa src/hooks.server.ts:

      src/hooks.server.ts
      import type { Handle } from "@sveltejs/kit";import { getLocalizedUrl } from "intlayer";import { getLocale } from "$lib/getLocale";export const handle: Handle = async ({ event, resolve }) => {  const detectedLocale = getLocale(event);  // Kiểm tra xem đường dẫn hiện tại đã bắt đầu bằng một locale chưa (ví dụ: /fr, /en)  const pathname = event.url.pathname;  const targetPathname = getLocalizedUrl(pathname, detectedLocale);  // Nếu KHÔNG có locale trong URL (ví dụ: người dùng truy cập "/"), chuyển hướng họ  if (targetPathname !== pathname) {    return new Response(undefined, {      headers: { Location: targetPathname },      status: 307, // Chuyển hướng tạm thời    });  }  return resolve(event, {    transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale),  });};

      Sau đó, tạo một helper để lấy locale của người dùng từ request event:

      src/lib/getLocale.ts
      import {  configuration,  getLocaleFromStorage,  localeDetector,  type Locale,} from "intlayer";import type { RequestEvent } from "@sveltejs/kit";/** * Lấy ngôn ngữ của người dùng từ sự kiện request. * Hàm này được sử dụng trong hook `handle` tại `src/hooks.server.ts`. * * Đầu tiên, nó cố gắng lấy ngôn ngữ từ bộ nhớ Intlayer (cookies hoặc header tùy chỉnh). * Nếu không tìm thấy ngôn ngữ, nó sẽ dùng phương pháp thương lượng "Accept-Language" của trình duyệt. * * @param event - Sự kiện request từ SvelteKit * @returns Ngôn ngữ của người dùng */export const getLocale = (event: RequestEvent): Locale => {  const defaultLocale = configuration?.internationalization?.defaultLocale;  // Cố gắng lấy ngôn ngữ từ bộ nhớ Intlayer (Cookies hoặc headers)  const storedLocale = getLocaleFromStorage({    // Truy cập cookies của SvelteKit    getCookie: (name: string) => event.cookies.get(name) ?? null,    // Truy cập headers của SvelteKit    getHeader: (name: string) => event.request.headers.get(name) ?? null,  });  if (storedLocale) {    return storedLocale;  }  // Dự phòng sử dụng đàm phán "Accept-Language" của trình duyệt  const negotiatorHeaders: Record<string, string> = {};  // Chuyển đổi đối tượng Headers của SvelteKit thành Record<string, string> thuần  event.request.headers.forEach((value, key) => {    negotiatorHeaders[key] = value;  });  // Kiểm tra locale từ header `Accept-Language`  const userFallbackLocale = localeDetector(negotiatorHeaders);  if (userFallbackLocale) {    return userFallbackLocale;  }  // Trả về locale mặc định nếu không tìm thấy kết quả phù hợp  return defaultLocale;};
      getLocaleFromStorage sẽ kiểm tra locale từ header hoặc cookie tùy theo cấu hình của bạn. Xem thêm tại Cấu hình để biết chi tiết.
      Hàm localeDetector sẽ xử lý header Accept-Language và trả về kết quả phù hợp nhất.

      Nếu locale chưa được cấu hình, chúng ta muốn trả về lỗi 404. Để dễ dàng hơn, ta có thể tạo một hàm match để kiểm tra xem locale có hợp lệ hay không:

      /src/params/locale.ts
      export const match = (param: Locale = defaultLocale): boolean =>  locales.includes(param);

      Lưu ý: Đảm bảo rằng file src/app.d.ts của bạn bao gồm định nghĩa locale:

      typescript
      declare global {  namespace App {    interface Locals {      locale: import("intlayer").Locale;    }  }}

      Đối với file +layout.svelte, chúng ta có thể xóa hết mọi thứ, chỉ giữ lại nội dung tĩnh, không liên quan đến i18n:

      src/+layout.svelte
      <script lang="ts">     import './layout.css';    let { children } = $props();</script><div class="app">    {@render children()}</div><style>    .app {    /*  */    }</style>

      Sau đó, tạo một trang và layout mới trong nhóm [[locale=locale]]:

      src/routes/[[locale=locale]]/+layout.ts
      import type { Load } from "@sveltejs/kit";import { defaultLocale, type Locale } from "intlayer";export const prerender = true;// Sử dụng kiểu Load chungexport const load: Load = ({ params }) => {  const locale: Locale = (params.locale as Locale) ?? defaultLocale;  return {    locale,  };};
      src/routes/[[locale=locale]]/+layout.svelte
      <script lang="ts">    import type { Snippet } from 'svelte';    import { useIntlayer, setupIntlayer } from "svelte-intlayer";    import Header from './Header.svelte';    import type { LayoutData } from './$types';    let { children, data }: { children: Snippet, data: LayoutData } = $props();    // Khởi tạo Intlayer với locale lấy từ route  $effect(() => {      setupIntlayer(data.locale);  });    // Sử dụng từ điển nội dung layout    const layoutContent = useIntlayer('layout');</script><Header /><main>    {@render children()}</main><footer>    <p>        {$layoutContent.footer.prefix.value}{' '}        <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '}        {$layoutContent.footer.suffix.value}    </p></footer><style>  /*  */</style>
      src/routes/[[locale=locale]]/+page.ts
      export const prerender = true;
      src/routes/[[locale=locale]]/+page.svelte
      <script lang="ts">    import { useIntlayer } from "svelte-intlayer";    // Sử dụng từ điển nội dung trang chủ    const homeContent = useIntlayer('home');</script><svelte:head>    <title>{$homeContent.title.value}</title></svelte:head><section>    <h1>        {$homeContent.title}    </h1></section><style>  /*  */</style>

    8. Liên kết quốc tế hóa

      Tùy chọn

      Để tối ưu SEO, nên thêm tiền tố locale vào các route của bạn (ví dụ: /en/about, /fr/about). Thành phần này tự động thêm tiền tố locale hiện tại vào bất kỳ liên kết nào.

      src/lib/components/LocalizedLink.svelte
      <script lang="ts">  import { getLocalizedUrl } from "intlayer";  import { useLocale } from "svelte-intlayer";  let { href = "" } = $props();  const { locale } = useLocale();  // Trợ giúp thêm tiền tố URL với locale hiện tại  $: localizedHref = getLocalizedUrl(href, $locale);</script><a href={localizedHref}>  <slot /></a>

      Nếu bạn sử dụng goto từ SvelteKit, bạn có thể dùng cùng logic với getLocalizedUrl để điều hướng đến URL đã được địa phương hóa:

      typescript
      import { goto } from "$app/navigation";import { getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";const { locale } = useLocale();const localizedPath = getLocalizedUrl("/about", $locale);goto(localizedPath); // Điều hướng đến /en/about hoặc /fr/about tùy theo locale

    9. Bộ chuyển đổi ngôn ngữ

      Tùy chọn

      Để cho phép người dùng chuyển đổi ngôn ngữ, cập nhật URL.

      src/lib/components/LanguageSwitcher.svelte
      <script lang="ts">  import { getLocalizedUrl, getLocaleName } from 'intlayer';  import { useLocale } from "svelte-intlayer";  import { page } from '$app/stores';  import { goto } from '$app/navigation';  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (newLocale) => {      const localizedPath = getLocalizedUrl($page.url.pathname, newLocale);      goto(localizedPath);    },  });</script><ul class="locale-list">  {#each availableLocales as localeEl}    <li>      <a        href={getLocalizedUrl($page.url.pathname, localeEl)}        onclick={(e) => {          e.preventDefault();          setLocale(localeEl); // Sẽ đặt locale trong store và kích hoạt onLocaleChange        }}        class:active={$locale === localeEl}      >        {getLocaleName(localeEl)}      </a>    </li>  {/each}</ul><style>  /* */</style>

    10. Thêm proxy backend

      Tùy chọn

      Để thêm proxy backend vào ứng dụng SvelteKit của bạn, bạn có thể sử dụng hàm intlayerProxy được cung cấp bởi plugin vite-intlayer. Plugin này sẽ tự động phát hiện locale tốt nhất cho người dùng dựa trên URL, cookie và sở thích ngôn ngữ trình duyệt.

      vite.config.ts
      import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";import { sveltekit } from "@sveltejs/kit/vite";// https://vitejs.dev/config/export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    intlayer(),    sveltekit(),  ],],});

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

      Để có thể hiển thị bộ chọn trình chỉnh sửa intlayer, bạn sẽ phải sử dụng cú pháp component trong nội dung intlayer của mình.

      Component.svelte
      <script lang="ts">  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("component");</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 như một component (bắt buộc bởi trình chỉnh sửa) -->  {@const Component = $content.component}<Component /></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 Git

    Khuyến nghị bỏ qua các tệp được tạo bởi Intlayer.

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

    Đi xa hơn

    • Trình chỉnh sửa trực quan: Tích hợp Trình chỉnh sửa trực quan Intlayer để chỉnh sửa bản dịch trực tiếp từ giao diện người dùng.
    • CMS: Đưa việc quản lý nội dung của bạn ra bên ngoài bằng cách sử dụng Intlayer CMS.
    Vite và Svelte
    Vite và Preact