Creation:2026-04-24Last update:2026-05-31

    Dịch trang web Astro + Lit của bạn với Intlayer | Đa ngôn ngữ (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ư astro-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 Astro bằng cách cung cấp định tuyến đa ngôn ngữ, sơ đồ trang web 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ấu hình Intlayer trong Astro + Lit

    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 trình quản lý gói ưa thích của bạn:

      bash
      npm install intlayer astro-intlayer lit lit-intlayer @astrojs/litnpx intlayer init

      • intlayer Gói cốt lõi cung cấp các công cụ i18n để quản lý cấu hình, bản dịch, khai báo nội dung, chuyển mã và các lệnh CLI.

      • astro-intlayer Plugin tích hợp Astro để kết nối Intlayer với trình đóng gói Vite; nó cũng bao gồm 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.

      • lit Gói Lit cốt lõi để xây dựng các Web Components nhanh và nhẹ.

      • lit-intlayer Gói để tích hợp Intlayer vào các ứng dụng Lit. Nó cung cấp các hook dựa trên ReactiveController (useIntlayer, useLocale, v.v.) để tự động thông báo cho LitElement render lại khi ngôn ngữ thay đổi.

      • @astrojs/lit Tích hợp chính thức của Astro cho phép sử dụng các Lit custom elements bên trong các trang Astro.

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

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

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      Locales.VIETNAMESE,      // 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 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.v. Để biết danh sách đầy đủ các tham số có sẵn, hãy xem tài liệu cấu hình.

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

      Thêm plugin intlayer vào cấu hình Astro và tích hợp Lit của bạn.

      astro.config.ts
      // @ts-checkimport { intlayer } from "astro-intlayer";import lit from "@astrojs/lit";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer(), lit()],});
      Plugin tích hợp intlayer() được sử dụng để tích hợp Intlayer với Astro. Nó đảm bảo việc tạo các file khai báo nội dung và theo dõi chúng trong chế độ phát triển. Nó xác định các biến môi trường Intlayer bên trong ứng dụng Astro và cung cấp các alias để tối ưu hóa hiệu suất.
      Tích hợp lit() cho phép sử dụng các Lit custom elements bên trong các trang Astro.

    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 của bạn để lưu trữ các bản dịch:

      src/components/lit/app.content.ts
      import { t, type Dictionary } from "intlayer";const litDemoContent = {  key: "lit-demo",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      vi: "Xin chào thế giới",    }),    description: t({      en: "Welcome to my multilingual Astro + Lit site.",      fr: "Bienvenue sur mon site Astro + Lit multilingue.",      es: "Bienvenido a mi sitio Astro + Lit multilingüe.",      vi: "Chào mừng bạn đến với trang web Astro + Lit đa ngôn ngữ của tôi.",    }),  },} satisfies Dictionary;export default litDemoContent;
      Các khai báo nội dung có thể được định nghĩa ở bất kỳ đâu trong ứng dụng của bạn, miễn là chúng nằm trong contentDir (mặc định là ./src) và khớ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 thông tin, hãy xem tài liệu khai báo nội dung.

    5. Sử dụng nội dung trong Astro

      Bạn có thể sử dụng các từ điển trực tiếp trong các file .astro bằng cách sử dụng các hàm hỗ trợ cốt lõi được xuất từ intlayer. Bạn cũng nên thêm metadata cho SEO (như hreflang và liên kết canonical) vào mỗi trang. Các Lit custom elements được nhập qua khối <script> phía client và được đặt trong body.

      src/pages/[...locale]/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { greeting } = getIntlayer("lit-demo", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{greeting}</title>    <!-- Liên kết Canonical -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Liên kết Hreflang -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <!-- Lit custom element - nhận ngôn ngữ được phát hiện bởi máy chủ dưới dạng thuộc tính -->    <lit-demo locale={locale}></lit-demo>  </body></html><script>  import "../../components/lit/LitDemo";</script>
      Nếu bạn muốn sử dụng nội dung của mình trong một thuộc tính chuỗi, chẳng hạn như alt, title, href, aria-label, v. b., bạn có thể sử dụng giá trị của hàm, như:
      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 ý về thiết lập định tuyến: Cấu trúc thư mục bạn sử dụng phụ thuộc vào cài đặt middleware.routing trong intlayer.config.ts:

      • prefix-no-default (mặc định): Giữ ngôn ngữ mặc định ở root (không có tiền tố) và thêm tiền tố cho các ngôn ngữ khác. Sử dụng [...locale] để bao gồm tất cả các trường hợp.
      • prefix-all: Tất cả các URL đều có tiền tố ngôn ngữ. Bạn có thể sử dụng [locale] tiêu chuẩn nếu không cần xử lý root riêng biệt.
      • search-param hoặc no-prefix: Không yêu cầu các thư mục ngôn ngữ. Ngôn ngữ được quản lý qua tham số truy vấn hoặc cookie.

    6. Tạo một Lit Custom Element

      Tạo một Lit custom element. Gọi installIntlayer trong connectedCallback bằng cách sử dụng thuộc tính locale dựa trên máy chủ để khởi tạo singleton quản lý bản dịch ở phía client.

      src/components/lit/LitDemo.ts
      import { LitElement, html } from "lit";import { installIntlayer, useIntlayer, useLocale } from "lit-intlayer";import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";class LitDemo extends LitElement {  static properties = {    locale: { type: String },  };  locale: LocalesValues = "en" as LocalesValues;  private _content = useIntlayer(this, "lit-demo");  private _localeCtrl = useLocale(this, {    onLocaleChange: (newLocale: LocalesValues) => {      window.location.href = getLocalizedUrl(        window.location.pathname,        newLocale      );    },  });  override connectedCallback() {    super.connectedCallback();    // Khởi tạo với ngôn ngữ được máy chủ phát hiện    installIntlayer({ locale: this.locale as any });  }  override render() {    const { greeting, description } = this._content;    const {      locale: currentLocale,      availableLocales,      setLocale,    } = this._localeCtrl;    return html`      <div>        <h1>${greeting}</h1>        <p>${description}</p>        <!-- Bộ chuyển đổi ngôn ngữ render bên trong LitElement -->        <div class="locale-switcher">          <span class="switcher-label">Thay đổi ngôn ngữ:</span>          <div class="locale-buttons">            ${availableLocales.map(              (localeItem) => html`                <button                  class="locale-btn ${localeItem === currentLocale                    ? "active"                    : ""}"                  ?disabled=${localeItem === currentLocale}                  @click=${() => setLocale(localeItem)}                >                  <span class="ls-own-name">${getLocaleName(localeItem)}</span>                  <span class="ls-current-name"                    >${getLocaleName(localeItem, currentLocale)}</span                  >                  <span class="ls-code">${localeItem.toUpperCase()}</span>                </button>              `            )}          </div>        </div>      </div>    `;  }}customElements.define("lit-demo", LitDemo);
      Thuộc tính locale được truyền từ trang Astro (phát hiện phía máy chủ) và được sử dụng trong connectedCallback để khởi động installIntlayer, thiết lập ngôn ngữ ban đầu cho tất cả các ReactiveController hook bên trong thành phần.
      useIntlayer được đăng ký như một ReactiveController. Nó sẽ tự động yêu cầu thành phần render lại khi ngôn ngữ thay đổi, do đó không cần thêm logic đăng ký (subscription) nào.

    7. Thêm bộ chuyển đổi ngôn ngữ

      Chức năng chuyển đổi ngôn ngữ được tích hợp trực tiếp vào phương thức render() của Lit custom element (xem Bước 6 ở trên). Nó sử dụng useLocale từ lit-intlayer và điều hướng đến URL bản địa hóa khi người dùng chọn ngôn ngữ mới:

      src/components/lit/LitDemo.ts
      // Bên trong lớp LitElement, sau khi thiết lập useLocale từ Bước 6:private _localeCtrl = useLocale(this, {  onLocaleChange: (newLocale: LocalesValues) => {    // Điều hướng đến URL bản địa hóa khi thay đổi ngôn ngữ    window.location.href = getLocalizedUrl(window.location.pathname, newLocale);  },});override render() {  const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;  return html`    <div class="locale-switcher">      <span class="switcher-label">Thay đổi ngôn ngữ:</span>      <div class="locale-buttons">        ${availableLocales.map(          (localeItem) => html`            <button              class="locale-btn ${localeItem === currentLocale ? "active" : ""}"              ?disabled=${localeItem === currentLocale}              @click=${() => setLocale(localeItem)}            >              <span class="ls-own-name">${getLocaleName(localeItem)}</span>              <span class="ls-current-name">${getLocaleName(localeItem, currentLocale)}</span>              <span class="ls-code">${localeItem.toUpperCase()}</span>            </button>          `        )}      </div>    </div>  `;}

      Lưu ý về tính phản ứng trong Lit: useLocale trả về một ReactiveController. Khi setLocale được gọi, controller sẽ tự động yêu cầu một bản cập nhật render, cập nhật trạng thái của các nút mà không cần thao tác DOM thủ công.

      Lưu ý về tính bền vững: Việc sử dụng onLocaleChange để chuyển hướng qua window.location.href đảm bảo rằng một URL ngôn ngữ mới sẽ được truy cập. Điều này cho phép middleware Intlayer thiết lập cookie ngôn ngữ và ghi nhớ lựa chọn của người dùng cho các lần truy cập sau.

    8. Sitemap và Robots.txt

      Intlayer cung cấp các tiện ích để tự động tạo sơ đồ trang web (sitemap) bản địa hóa và file robots.txt của bạn.

      Sitemap

      Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

      The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

      Tạo src/pages/sitemap.xml.ts để tạo sơ đồ trang web bao gồm tất cả các route bản địa hóa của bạn.

      src/pages/sitemap.xml.ts
      import type { APIRoute } from "astro";import { generateSitemap, type SitemapUrlEntry } from "intlayer";const pathList: SitemapUrlEntry[] = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";export const GET: APIRoute = async ({ site }) => {  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });  return new Response(xmlOutput, {    headers: { "Content-Type": "application/xml" },  });};

      Robots.txt

      Tạo src/pages/robots.txt.ts để kiểm soát hoạt động thu thập thông tin của các công cụ tìm kiếm.

      src/pages/robots.txt.ts
      import type { APIRoute } from "astro";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);export const GET: APIRoute = ({ site }) => {  const robotsTxt = [    "User-agent: *",    "Allow: /",    ...disallowedPaths.map((path) => `Disallow: ${path}`),    "",    `Sitemap: ${new URL("/sitemap.xml", site).href}`,  ].join("\n");  return new Response(robotsTxt, {    headers: { "Content-Type": "text/plain" },  });};

    9. 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 cơ chế mở rộng module (module augmentation) để tận dụng TypeScript, làm cho cơ sở mã của bạn mạnh mẽ hơn. Nếu bạn đang sử dụng cú pháp decorators, hãy đảm bảo rằng bạn đã bật experimentalDecorators trong compiler options.

    Autocompletion

    Translation Error

    Đả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: {    // ...    experimentalDecorators: true,    useDefineForClassFields: false, // Bắt buộc để hỗ trợ decorators trong Lit  },  "include": [    // ... cấu hình TypeScript hiện tại của bạn    ".intlayer/**/*.ts", // Bao gồm các kiểu dữ liệu được tạo tự động  ],}

    Cấu hình Git

    Khuyên bạn nên bỏ qua các file được tạo bởi Intlayer. Điều này ngăn chúng được commit vào kho lưu trữ Git của bạn.

    Để làm điều đó, hãy thêm các hướng dẫn sau vào file .gitignore của bạn:

    bash
    # Bỏ qua các file đượ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 chính thức cho VS Code.

    Cài đặt từ VS Code Marketplace

    Tiện ích này sẽ 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 còn thiếu.
    • Xem trước trực tiếp nội dung đã dịch.
    • Các hành động nhanh để tạo và cập nhật bản dịch dễ dàng.

    Để biết thêm thông tin về cách sử dụng tiện ích này, hãy xem tài liệu tiện ích VS Code.

    Tìm hiểu sâu hơn

    Nếu bạn muốn tìm hiểu thêm, bạn cũng có thể triển khai Visual Editor hoặc sử dụng CMS để quản lý nội dung bên ngoài.

    Astro và Preact
    Astro và Vanilla JS