Đặ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
Bằng cách tích hợp Intlayer MCP Server vào trợ lý AI ưa thích của bạn, bạn có thể truy xuất toàn bộ tài liệu trực tiếp từ ChatGPT, DeepSeek, Cursor, VSCode, v.v.
Xem tài liệu MCP ServerLịch sử phiên bản
- Cập nhật tài liệuv6.5.23/10/2025
- Thêm cho Tanstack Startv5.8.19/9/2025
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 AnhNếu bạn có ý tưởng để cải thiện tài liệu này, vui lòng đóng góp bằng cách gửi pull request trên GitHub.
Liên kết GitHub tới tài liệuSao chép Markdown của tài liệu vào bộ nhớ tạm
Dịch trang web Tanstack Start của bạn bằng Intlayer | Quốc tế hóa (i18n)
Mục lục
Hướng dẫn này trình bày cách tích hợp Intlayer để thực hiện quốc tế hóa liền mạch trong các dự án Tanstack Start với định tuyến nhận biết locale, hỗ trợ TypeScript và các thực hành phát triển hiện đại.
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.
Với Intlayer, bạn có thể:
- Dễ dàng quản lý bản dịch bằng cách sử dụng từ điển khai báo ở cấp thành phần.
- Định vị động metadata, các tuyến đường và nội dung.
- Đảm bảo hỗ trợ TypeScript với các kiểu được tạo tự động, cải thiện tính năng tự động hoàn thành và phát hiện lỗi.
- Tận hưởng các tính năng nâng cao, như phát hiện và chuyển đổi locale động.
- Kích hoạt định tuyến nhận biết locale với hệ thống định tuyến dựa trên file của Tanstack Start.
Hướng dẫn từng bước để thiết lập Intlayer trong ứng dụng Tanstack Start
Xem Mẫu Ứng dụng trên GitHub.
Bước 1: Tạo Dự Án
Bắt đầu bằng cách tạo một dự án TanStack Start mới theo hướng dẫn Bắt đầu dự án mới trên trang web TanStack Start.
Bước 2: Cài Đặt Các Gói Intlayer
Cài đặt các gói cần thiết bằng trình quản lý gói bạn ưa thích:
npm install intlayer react-intlayernpm install vite-intlayer --save-dev- 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.
react-intlayer
Gói tích hợp Intlayer với ứng dụng React. Nó cung cấp các context provider và hook cho việc quốc tế hóa trong React.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ữ ưu tiên của người dùng, quản lý cookie và xử lý chuyển hướng URL.
Bước 3: Cấu hình dự án của bạn
Tạo một file cấu hình để cấu hình các ngôn ngữ cho ứng dụng của bạn:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import type { IntlayerConfig } from "intlayer";import { Locales } from "intlayer";const config: IntlayerConfig = { internationalization: { defaultLocale: Locales.ENGLISH, locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], },};export default config;Thông qua file cấu hình này, bạn có thể thiết lập URL theo ngôn ngữ, 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.
Bước 4: 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:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [reactRouter(), tsconfigPaths(), 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 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 suất.
Bước 5: Tạo Các Thành Phần Layout
Thiết lập layout gốc của bạn và các layout theo ngôn ngữ cụ thể:
Layout Gốc
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { const { defaultLocale } = useLocale(); const { locale } = Route.useParams(); return ( <IntlayerProvider locale={defaultLocale}> <Outlet /> </IntlayerProvider> );}Bước 6: 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:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import type { Dictionary } from "intlayer";import { t } from "intlayer";const appContent = { content: { links: { about: t({ en: "About", es: "Acerca de", fr: "À propos", }), home: t({ en: "Home", es: "Inicio", fr: "Accueil", }), }, meta: { description: t({ vi: "Đây là ví dụ về việc sử dụng Intlayer với TanStack Router", en: "This is an example of using Intlayer with TanStack Router", es: "Este es un ejemplo de uso de Intlayer con TanStack Router", fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router", }), }, title: t({ vi: "Chào mừng đến với Intlayer + TanStack Router", en: "Welcome to Intlayer + TanStack Router", es: "Bienvenido a Intlayer + TanStack Router", fr: "Bienvenue à Intlayer + TanStack Router", }), }, key: "app",} 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à ./app). 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,mjx,cjs,cjx}).
Để biết thêm chi tiết, hãy tham khảo tài liệu khai báo nội dung.
Bước 7: Tạo các Component và Hook nhận biết Locale
Tạo một component LocalizedLink để điều hướng nhận biết locale:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import type { FC } from "react";import { Link, type LinkComponentProps } from "@tanstack/react-router";import { useLocale } from "react-intlayer";import { getPrefix } from "intlayer";export const LOCALE_ROUTE = "{-$locale}" as const;// Tiện ích chínhexport type RemoveLocaleParam<T> = T extends string ? RemoveLocaleFromString<T> : T;export type To = RemoveLocaleParam<LinkComponentProps["to"]>;type CollapseDoubleSlashes<S extends string> = S extends `${infer H}//${infer T}` ? CollapseDoubleSlashes<`${H}/${T}`> : S;type LocalizedLinkProps = { to?: To;} & Omit<LinkComponentProps, "to">;// Các hàm trợ giúptype RemoveAll< S extends string, Sub extends string,> = S extends `${infer H}${Sub}${infer T}` ? RemoveAll<`${H}${T}`, Sub> : S;type RemoveLocaleFromString<S extends string> = CollapseDoubleSlashes< RemoveAll<S, typeof LOCALE_ROUTE>>;export const LocalizedLink: FC<LocalizedLinkProps> = (props) => { const { locale } = useLocale(); const { localePrefix } = getPrefix(locale); return ( <Link {...props} params={{ locale: localePrefix, ...(typeof props?.params === "object" ? props?.params : {}), }} to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]} /> );};Component này có hai mục tiêu:
- Loại bỏ tiền tố {-$locale} không cần thiết khỏi URL.
- Tiêm tham số locale vào URL để đảm bảo người dùng được chuyển hướng trực tiếp đến route đã được địa phương hóa.
Sau đó, chúng ta có thể tạo một hook useLocalizedNavigate để điều hướng theo lập trình:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import { useNavigate } from "@tanstack/react-router";import { getPrefix } from "intlayer";import { useLocale } from "react-intlayer";import { LOCALE_ROUTE } from "@/components/localized-link";import type { FileRouteTypes } from "@/routeTree.gen";type StripLocalePrefix<T extends string> = T extends | `/${typeof LOCALE_ROUTE}` | `/${typeof LOCALE_ROUTE}/` ? "/" : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}` ? `/${Rest}` : never;type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;type LocalizedNavigate = { (to: LocalizedTo): ReturnType<ReturnType<typeof useNavigate>>; ( opts: { to: LocalizedTo } & Record<string, unknown> ): ReturnType<ReturnType<typeof useNavigate>>;};export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const localizedNavigate: LocalizedNavigate = (args: any) => { const { localePrefix } = getPrefix(locale); if (typeof args === "string") { return navigate({ to: `/${LOCALE_ROUTE}${args}`, params: { locale: localePrefix }, }); } const { to, ...rest } = args; const localizedTo = `/${LOCALE_ROUTE}${to}` as any; return navigate({ to: localizedTo, params: { locale: localePrefix, ...rest } as any, }); }; return localizedNavigate;};Bước 8: Sử dụng Intlayer trong các Trang của Bạn
Truy cập các từ điển nội dung của bạn trong toàn bộ ứng dụng:
Trang Chủ Đã Được Địa Phương Hóa
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";import { useIntlayer } from "react-intlayer";import LocaleSwitcher from "@/components/locale-switcher";import { LocalizedLink } from "@/components/localized-link";import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: ({ params }) => { const { locale } = params; const metaContent = getIntlayer("app", locale); return { meta: [ { title: metaContent.title }, { content: metaContent.meta.description, name: "description" }, ], }; },});function RouteComponent() { const content = useIntlayer("app"); const navigate = useLocalizedNavigate(); return ( <div> <div> {content.title} <LocaleSwitcher /> <div> <LocalizedLink to="/">{content.links.home}</LocalizedLink> <LocalizedLink to="/about">{content.links.about}</LocalizedLink> </div> <div> <button onClick={() => navigate({ to: "/" })}> {content.links.home} </button> <button onClick={() => navigate({ to: "/about" })}> {content.links.about} </button> </div> </div> </div> );}Để tìm hiểu thêm về hook useIntlayer, hãy tham khảo tài liệu.
Bước 9: Tạo một Thành phần Chuyển đổi Ngôn ngữ
Tạo một thành phần để cho phép người dùng thay đổi ngôn ngữ:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import type { FC } from "react";import { useLocation } from "@tanstack/react-router";import { getHTMLTextDir, getLocaleName, getPathWithoutLocale, getPrefix,} from "intlayer";import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";import { LocalizedLink, To } from "./localized-link";export const LocaleSwitcher: FC = () => { const { localeSwitcherLabel } = useIntlayer("locale-switcher"); const { pathname } = useLocation(); const { availableLocales, locale } = useLocale(); const pathWithoutLocale = getPathWithoutLocale(pathname); return ( <ol> {availableLocales.map((localeEl) => ( <li key={localeEl}> <LocalizedLink aria-current={localeEl === locale ? "page" : undefined} aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeEl)}`} onClick={() => setLocaleInStorage(localeEl)} params={{ locale: getPrefix(localeEl).localePrefix }} > <span> {/* Mã ngôn ngữ - ví dụ: FR */} {localeItem} </span> <span> {/* Ngôn ngữ theo mã ngôn ngữ của chính nó - ví dụ: Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Ngôn ngữ theo mã ngôn ngữ hiện tại - ví dụ: Francés khi mã ngôn ngữ hiện tại là Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Ngôn ngữ bằng tiếng Anh - ví dụ: French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </LocalizedLink> </li> ))} </ol> );};Để tìm hiểu thêm về hook useLocale, tham khảo tài liệu.
Bước 10: Thêm quản lý thuộc tính HTML (Tùy chọn)
Tạo một hook để quản lý các thuộc tính lang và dir của HTML:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
// src/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};Sau đó sử dụng nó trong component gốc của bạn:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // nhập hookexport const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { useI18nHTMLAttributes(); // thêm dòng này const { defaultLocale } = useLocale(); const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale ?? defaultLocale}> <Outlet /> </IntlayerProvider> );}Bước 11: Thêm middleware (Tùy chọn)
Bạn cũng có thể sử dụng intlayerProxy để thêm routing phía server vào ứ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 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.
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
import { reactRouter } from "@react-router/dev/vite";import tailwindcss từ "@tailwindcss/vite";import { defineConfig } từ "vite";import { intlayer, intlayerProxy } từ "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [ tailwindcss(), reactRouter(), tsconfigPaths(), intlayer(), intlayerProxy(), ],});Bước 12: Cấu hình TypeScript (Tùy chọn)
Intlayer sử dụng module augmentation để tận dụng các lợi ích của TypeScript và làm cho codebase của bạn mạnh mẽ hơn.
Đảm bảo cấu hình TypeScript của bạn bao gồm các kiểu được tạo tự động:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
{ // ... các cấu hình hiện có của bạn include: [ // ... các include hiện có của bạn ".intlayer/**/*.ts", // Bao gồm các kiểu được tạo tự động ],}Cấu hình Git
Khuyến nghị bạn nên bỏ qua các file được tạo 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 hướng dẫn sau vào file .gitignore của bạn:
Sao chép đoạn mã vào khay nhớ tạm (clipboard)
# Bỏ qua các file được tạo bởi Intlayer.intlayerTiệ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
Để đi 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.
Tham khảo Tài liệu
Hướng dẫn toàn diện này cung cấp tất cả những gì bạn cần để tích hợp Intlayer với Tanstack Start cho một ứng dụng được quốc tế hóa hoàn toàn với định tuyến nhận biết locale và hỗ trợ TypeScript.