Đặt câu hỏi và nhận tóm tắt tài liệu bằng cách tham chiếu trang này và nhà cung cấp AI bạn chọn
Lịch sử phiên bản
- "Cập nhật cách sử dụng API useIntlayer của Solid sang truy cập thuộc tính trực tiếp"v8.9.04/5/2026
- "Lịch sử ban đầu"v8.4.1023/3/2026
Nội dung của trang này đã được dịch bằng AI.
Xem phiên bản mới nhất của nội dung gốc bằng tiếng AnhIf you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.
GitHub link to the documentationCopy doc Markdown to clipboard
Dịch trang web Vite và Lit của bạn bằng Intlayer | Quốc tế hóa (i18n)
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ư lit-localize 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 Lit bằng cách cung cấp phạm vi nội dung ở cấp Thành phần Web, 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à Lit
Cài đặt các phụ thuộc
Cài đặt các gói cần thiết bằng npm:
bashSao chép mãSao chép mã vào clipboard
npm install intlayer lit-intlayernpm install vite-intlayer --save-devnpx intlayer initintlayer
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ã và các lệnh CLI.
lit-intlayer Gói tích hợp Intlayer với các ứng dụng Lit. Nó cung cấp các hook dựa trên
ReactiveController(useIntlayer,useLocale, v.v.) để các LitElement tự động render lại khi ngôn ngữ thay đổi.vite-intlayer Bao gồm plugin Vite để tích hợp Intlayer với trình đóng gói Vite, 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.
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.tsSao chép mãSao chép mã vào clipboard
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 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 nhật ký Intlayer trong console, và nhiều hơn nữa. Để biết danh sách đầy đủ các tham số có sẵn, hãy tham khảo tài liệu cấu hình.
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.tsSao chép mãSao chép mã vào clipboard
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à giám sát chúng trong chế độ phát triển. Nó xác định 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.Khởi động Intlayer trong điểm đầu vào (entry point) của bạn
Gọi
installIntlayer()trước khi bất kỳ custom element nào được đăng ký để đối tượng ngôn ngữ toàn cầu (global locale singleton) sẵn sàng khi phần tử đầu tiên kết nối.src/main.tsSao chép mãSao chép mã vào clipboard
import { installIntlayer } from "lit-intlayer";// Phải được gọi trước khi bất kỳ LitElement nào được kết nối với DOM.installIntlayer();// Nhập và đăng ký các custom element của bạn.import "./my-element.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 kết xuất markdown:src/main.tsSao chép mãSao chép mã vào clipboard
import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";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.tsSao chép mãSao chép mã vào clipboard
import { t, type Dictionary } from "intlayer"; const appContent = { key: "app", content: { title: "Vite + Lit", viteLogo: t({ en: "Vite logo", fr: "Logo Vite", es: "Logo Vite", }), litLogo: t({ en: "Lit logo", fr: "Logo Lit", es: "Logo Lit", }), count: t({ en: "count is {{count}}", fr: "le compte est {{count}}", es: "el recuento es {{count}}", }), readTheDocs: t({ en: "Click on the Vite and Lit logos to learn more", fr: "Cliquez sur les logos Vite et Lit pour en savoir plus", es: "Haga clic en los logotipos de Vite và Lit 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 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.
Sử dụng Intlayer trong LitElement của bạn
Sử dụng
useIntlayerbên trong mộtLitElement. Nó trả về một proxyReactiveControllertự động kích hoạt render lại bất cứ khi nào ngôn ngữ hiện tại thay đổi - không cần thiết lập thêm.src/my-element.tsSao chép mãSao chép mã vào clipboard
import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement { @property({ type: Number }) count = 0; // useIntlayer đăng ký chính nó như một ReactiveController. // Phần tử sẽ tự động render lại khi ngôn ngữ thay đổi. private content = useIntlayer(this, "app"); override render() { const { content } = this; return html` <h1>${content.title}</h1> <img src="/vite.svg" alt=${content.viteLogo.value} /> <img src="/lit.svg" alt=${content.litLogo.value} /> <button @click=${() => this.count++}> ${content.count({ count: this.count })} </button> <p>${content.readTheDocs}</p> `; }}Khi bạn cần chuỗi đã dịch trong một thuộc tính HTML gốc (ví dụ:
alt,aria-label,title), hãy gọi.valuetrên nút lá:typescriptSao chép mãSao chép mã vào clipboard
html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;Thay đổi ngôn ngữ của nội dung
Tùy chọnĐể thay đổi ngôn ngữ của nội dung, hãy sử dụng phương thức
setLocaleđược cung cấp bởi controlleruseLocale.src/locale-switcher.tsSao chép mãSao chép mã vào clipboard
import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement { private locale = useLocale(this); private _onChange(e: Event) { const select = e.target as HTMLSelectElement; this.locale.setLocale(select.value as any); } override render() { return html` <select @change=${this._onChange}> ${this.locale.availableLocales.map( (loc) => html` <option value=${loc} ?selected=${loc === this.locale.locale}> ${getLocaleName(loc)} </option> ` )} </select> `; }}Render nội dung Markdown và HTML
Tùy chọnIntlayer hỗ trợ các khai báo nội dung
md()vàhtml(). Trong Lit, đầu ra đã biên dịch được chèn dưới dạng HTML thô thông qua directiveunsafeHTML.Render HTML đã biên dịch trong phần tử của bạn:
src/my-element.tsSao chép mãSao chép mã vào clipboard
import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement { private content = useIntlayer(this, "app"); override render() { return html` <div class="edit-note"> ${unsafeHTML(compileMarkdown(String(this.content.editNote)))} </div> `; }}TIP String(content.editNote)gọitoString()trênIntlayerNode, nó trả về chuỗi Markdown thô. Chuyển nó vàocompileMarkdownđể lấy chuỗi HTML, sau đó render bằng directiveunsafeHTMLcủa Lit.Thêm Routing bản địa hóa 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 một trình định tuyến phía máy khách cùng với các helper
localeMap/localeFlatMapcủa Intlayer, và plugin ViteintlayerProxyđể phát hiện ngôn ngữ phía máy chủ.Đầu tiên, thêm
intlayerProxyvào cấu hình Vite của bạn:Lưu ý rằng để sử dụng
intlayerProxytrong môi trường production, bạn cần chuyểnvite-intlayertừdevDependenciessangdependencies.vite.config.tsSao chép mãSao chép mã vào clipboard
import { defineConfig } from "vite"; import { intlayer, intlayerProxy } from "vite-intlayer"; export default defineConfig({ plugins: [intlayer(), intlayerProxy()], });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 sử dụng
useRewriteURLcùng với trình chuyển đổi ngôn ngữ:src/locale-switcher.tsSao chép mãSao chép mã vào clipboard
import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement { private locale = useLocale(this); // Tự động viết lại URL hiện tại khi ngôn ngữ thay đổi. private _rewriteURL = useRewriteURL(this); private _onChange(e: Event) { const select = e.target as HTMLSelectElement; this.locale.setLocale(select.value as any); } override render() { return html` <select @change=${this._onChange}> ${this.locale.availableLocales.map( (loc) => html` <option value=${loc} ?selected=${loc === this.locale.locale}> ${getLocaleName(loc)} </option> ` )} </select> `; }}Chuyển đổi các thuộc tính Language và Direction của HTML
Tùy chọnCập nhật các thuộc tính
langvàdircủa thẻ<html>để khớp với ngôn ngữ hiện tại nhằm mục đích truy cập và SEO.src/my-element.tsSao chép mãSao chép mã vào clipboard
import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement { private locale = useLocale(this, { onLocaleChange: (loc) => { document.documentElement.lang = loc; document.documentElement.dir = getHTMLTextDir(loc); }, }); override render() { return html`<!-- nội dung của bạn -->`; }}Trích xuất nội dung của các component
Tùy chọnNếu bạn có một codebase hiện có, việc chuyển đổi hàng nghìn tệp có thể mất nhiều thời gian.
Để giảm bớt quá trình này, Intlayer đề xuất một compiler / extractor để chuyển đổi các component của bạn và trích xuất nội dung.
Để thiết lập, bạn có thể thêm một phần
compilertrong tệpintlayer.config.tscủa mình:intlayer.config.tsSao chép mãSao chép mã vào clipboard
import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { // ... Các phần còn lại của cấu hình compiler: { /** * Cho biết liệu trình biên dịch có được bật hay không. */ enabled: true, /** * Xác định đường dẫn tệp đầu ra */ output: ({ fileName, extension }) => `./${fileName}${extension}`, /** * Cho biết liệu các component có được lưu sau khi được chuyển đổi hay không. * Bằng cách đó, trình biên dịch có thể chỉ cần chạy một lần để chuyển đổi ứng dụng, sau đó nó có thể bị xóa. */ saveComponents: false, /** * Tiền tố khóa từ điển */ dictionaryKeyPrefix: "", },};export default config;
(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ênxhtml: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/abouthoặc/about?lang=frtù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
Sao chép mã vào clipboard
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ùnggenerate-seo.mjscho ESM của Node. Nếu dùnggenerate-seo.js, đặt"type": "module"trongpackage.jsonhoặc bật ESM tương đương.
2. Chạy script trước Vite
Sao chép mã vào clipboard
{ "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 rằng cấu hình TypeScript của bạn bao gồm các kiểu được tạo tự động.
Sao chép mã vào clipboard
{ "compilerOptions": { // ... "experimentalDecorators": true, "useDefineForClassFields": false, }, "include": ["src", ".intlayer/**/*.ts"],}experimentalDecoratorsvàuseDefineForClassFields: falselà bắt buộc đối với Lit để hỗ trợ decorator.
Cấu hình Git
Khuyên 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 việc commit chúng lên kho lưu trữ Git của mình.
Để thực hiện việc này, bạn có thể thêm các hướng dẫn sau vào tệp .gitignore của mình:
Sao chép mã vào clipboard
# Bỏ qua các tệp do Intlayer tạo ra.intlayerTiệ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 thời gian thực cho các bản dịch bị thiếu.
- Xem trước trực tuyến nội dung đã dịch.
- Các 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 VS Code.
Tìm hiểu thêm
Để 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 thứ ba hóa nội dung của bạn bằng CMS.