Tác giả:
    Aymeric PINEAU
    Ngày tạo:2025-09-09Cập nhật lần cuối:2026-08-25

    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.

    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ư react-i18next hay use-intl, hay paraglide, 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àn toàn cho TanStack Start, cung cấp định tuyến đa ngôn ngữ, quản lý cookie, tạo sơ đồ trang web, tải nội dung động và tất cả các tính năng cần thiết để mở rộng nỗ lực quốc tế hóa (i18n) của bạn.

    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 Tanstack Start

    youtube.com
    ide.intlayer.org
    intlayer-tanstack-start-template.vercel.app

    Xem Mẫu Ứng dụng trên GitHub.

    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.

    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:

      bash
      npx intlayer init --interactive
      cờ --interactive là tùy chọn. Sử dụng intlayer-cli init nếu bạn là tác nhân AI.
      Lệnh này sẽ phát hiện môi trường của bạn và cài đặt các gói cần thiết. Ví dụ:
      bash
      npm install intlayer react-intlayer
npm 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.

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

      Kiến trúc

      Trong kiến trúc này, tất cả các tuyến đường được bản địa hóa đều được lồng dưới đoạn tuyến đường {-$locale}. Cách tiếp cận này đảm bảo mỗi ngôn ngữ có một URL chuyên dụng đồng thời cho phép tự động thêm tiền tố ngôn ngữ, xác thực và tối ưu hóa SEO.

      bash
      .
├── src
│   ├── components
│   │   ├── Header.tsx
│   │   ├── locale-switcher.content.ts
│   │   ├── locale-switcher.tsx
│   │   └── localized-link.tsx
│   ├── hooks
│   │   ├── useI18nHTMLAttributes.tsx
│   │   └── useLocalizedNavigate.ts
│   ├── routes
│   │   ├── {-$locale}
│   │   │   ├── 404.content.ts
│   │   │   ├── 404.tsx
│   │   │   ├── about.content.ts
│   │   │   ├── about.tsx
│   │   │   ├── index.content.tsx
│   │   │   ├── index.tsx
│   │   │   └── route.tsx             # Locale layout & prefix validation
│   │   ├── __root.tsx                # Root route with IntlayerProvider
│   │   └── sitemap[.]xml.ts
│   ├── router.tsx
│   └── styles.css
├── intlayer.config.ts
├── package.json
├── tsconfig.json
└── vite.config.ts

      Cấu hình

      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:

      intlayer.config.ts
      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.

    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:

      vite.config.ts
      import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

const config = defineConfig({
  plugins: [
    nitro(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    viteReact(),
  ],
});

export default config;
      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.

    5. Tạo Root Layout

      Cấu hình root layout của bạn để hỗ trợ quốc tế hóa bằng cách sử dụng useParams để phát hiện locale hiện tại và đặt các thuộc tính lang và dir trên thẻ html.

      src/routes/__root.tsx
      import {
  createRootRouteWithContext,
  getRouteApi,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";
import { defaultLocale, getHTMLTextDir } from "intlayer";
import { type ReactNode } from "react";
import { IntlayerProvider } from "react-intlayer";

const localeRoute = getRouteApi("/{-$locale}");

export const Route = createRootRouteWithContext<{}>()({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        content: "width=device-width, initial-scale=1",
        name: "viewport",
      },
      {
        title: "TanStack Start Starter",
      },
    ],
  }),

  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: ReactNode }) {
  const params = localeRoute.useParams();
  const locale = params?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
        <Scripts />
      </body>
    </html>
  );
}

    6. Tạo Layout Locale

      Tạo một layout xử lý tiền tố locale và thực hiện xác thực.

      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { validatePrefix } from "intlayer";

export const Route = createFileRoute("/{-$locale}")({
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // Xác thực tiền tố locale
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
});
      Ở đây, {-$locale} là một tham số route động được thay thế bằng locale hiện tại. Ký hiệu này làm cho slot trở nên tùy chọn, cho phép nó hoạt động với các chế độ định tuyến như 'prefix-no-default' v.v.

      Lưu ý rằng slot này có thể gây ra vấn đề nếu bạn sử dụng nhiều segment động trong cùng một route (ví dụ: /{-$locale}/other-path/$anotherDynamicPath/...). Đối với chế độ 'prefix-all', bạn có thể muốn chuyển slot thành $locale thay thế. Đối với chế độ 'no-prefix' hoặc 'search-params', bạn có thể xóa hoàn toàn slot.

    7. 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/contents/page.content.ts
      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: {
      title: t({
        en: "Welcome to Intlayer + TanStack Router",
        es: "Bienvenido a Intlayer + TanStack Router",
        fr: "Bienvenue à Intlayer + TanStack Router",
      }),
      description: t({
        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",
      }),
    },
  },
  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,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.

    8. 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:

      src/components/localized-link.tsx
      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;

export type To = StripLocalePrefix<LinkComponentProps["to"]>;

export type StripLocalePrefix<T extends string | undefined> = T extends
  `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
  ? "/"
  : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
    ? `/${Rest}`
    : T;

type LocalizedLinkProps = {
  to?: To;
} & Omit<LinkComponentProps, "to">;

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:

      src/hooks/useLocalizedNavigate.tsx
      import { useNavigate } from "@tanstack/react-router";
import { getPrefix } from "intlayer";
import { useLocale } from "react-intlayer";
import type { StripLocalePrefix } from "@/components/localized-link";
import type { FileRouteTypes } from "@/routeTree.gen";

type NavigateFn = ReturnType<typeof useNavigate>;
type BaseNavigateOptions = Parameters<NavigateFn>[0];

type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;

export type LocalizedNavigateOptions = Omit<
  BaseNavigateOptions,
  "to" | "params"
> & {
  to: LocalizedTo;
  params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
};

type LocalizedNavigate = (
  options: LocalizedNavigateOptions
) => ReturnType<NavigateFn>;

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;
};

    9. Sử dụng Intlayer trong các Trang của Bạn

      Hãy dùng useIntlayer theo mặc định: đây là cách được khuyến nghị để đọc nội dung bên trong component, và trình biên dịch sẽ phân giải nó về đúng locale đang được render. Chỉ dùng getIntlayer / getIntlayerAsync bên ngoài cây React: head của route, loader và server function.

      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 Bản Địa Hóa

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
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,
});

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>
  );
}

      Nếu bạn muốn sử dụng nội dung của mình trong một thuộc tính string, chẳng hạn như alt, title, href, aria-label, v.v., bạn có thể sử dụng giá trị của hàm, như:

      tsx
      <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)} />
      Để tìm hiểu thêm về hook useIntlayer, hãy tham khảo tài liệu.

    10. Tạo 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ữ:

      src/components/locale-switcher.tsx
      import { useLocation } from "@tanstack/react-router";
import {
  getHTMLTextDir,
  getLocaleName,
  getPathWithoutLocale,
  getPrefix,
  Locales,
} from "intlayer";
import type { FC } from "react";
import { useLocale } from "react-intlayer";

import { LocalizedLink, type To } from "./localized-link";

export const LocaleSwitcher: FC = () => {
  const { pathname } = useLocation();

  const { availableLocales, locale, setLocale } = useLocale();

  const pathWithoutLocale = getPathWithoutLocale(pathname);

  return (
    <ol>
      {availableLocales.map((localeEl) => (
        <li key={localeEl}>
          <LocalizedLink
            aria-current={localeEl === locale ? "page" : undefined}
            onClick={() => setLocale(localeEl)}
            params={{ locale: getPrefix(localeEl).localePrefix }}
            to={pathWithoutLocale as To}
          >
            <span>
              {/* Locale - ví dụ FR */}
              {localeEl}
            </span>
            <span>
              {/* Ngôn ngữ trong Locale của chính nó - ví dụ Français */}
              {getLocaleName(localeEl, locale)}
            </span>
            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
              {/* Ngôn ngữ trong Locale hiện tại - ví dụ Francés khi Locale hiện tại được đặt thành Locales.SPANISH */}
              {getLocaleName(localeEl)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Ngôn ngữ trong tiếng Anh - ví dụ French */}
              {getLocaleName(localeEl, Locales.ENGLISH)}
            </span>
          </LocalizedLink>
        </li>
      ))}
    </ol>
  );
};
      Để tìm hiểu thêm về hook useLocale, hãy tham khảo tài liệu.

    11. Quản Lý Thuộc Tính HTML

      Như đã thấy trong Bước 5, bạn có thể quản lý các thuộc tính lang và dir của thẻ html bằng cách sử dụng useParams trong thành phần gốc của mình. Điều này đảm bảo rằng các thuộc tính chính xác được đặt trên máy chủ và máy khách.

      src/routes/__root.tsx
      const localeRoute = getRouteApi("/{-$locale}");

function RootDocument({ children }: { children: ReactNode }) {
  const params = localeRoute.useParams();
  const locale = params?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      {/* ... */}
    </html>
  );
}

    12. Thêm middleware

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

      Lưu ý rằng để sử dụng intlayerProxy trong production, bạn cần chuyển package vite-intlayer từ devDependencies sang dependencies.
      Kể từ Intlayer v9, intlayerProxy() được bao gồm trực tiếp trong plugin intlayer() và được bật theo mặc định thông qua tùy chọn routing.enableProxy (true theo mặc định). Đăng ký nó riêng như hình dưới đây giờ đây là tùy chọn: nó được giữ lại để tương thích ngược và cho các thiết lập cần kiểm soát thứ tự plugin. Đặt routing.enableProxy: false để từ chối. Xem ghi chú phát hành v9.
      vite.config.ts
      import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    nitro(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    viteReact(),
  ],
});

    13. Bản Địa Hóa Metadata của Bạn

      getIntlayer phân giải đồng bộ dựa trên từ điển đã hợp nhất, từ điển chứa mọi ngôn ngữ được khai báo. head vẫn đồng bộ và không có gì bị chờ đợi, nhưng toàn bộ từ điển đa ngôn ngữ được kéo vào phần tuyến đường được gửi đến trình duyệt.

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayer,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // Đường dẫn cho tuyến đường này

    const metaContent = getIntlayer("app", locale);

    return {
      links: [
        // Liên kết chính tắc: Trỏ đến trang được bản địa hóa hiện tại
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Thông báo cho Google về tất cả các phiên bản được bản địa hóa
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Cho người dùng ở các ngôn ngữ không phù hợp
        // Xác định ngôn ngữ dự phòng mặc định (thường là ngôn ngữ chính của bạn)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});

      Tốt nhất cho các từ điển metadata nhỏ, một số ngôn ngữ, hoặc trong khi tạo mẫu.

      getIntlayerAsync (có sẵn từ v9.4) hoạt động như getIntlayer, nhưng plugin xây dựng chỉ nó đến phần theo ngôn ngữ trong .intlayer/dynamic_dictionaries/ thay vì từ điển đã hợp nhất. Do đó, một trang chỉ vận chuyển ngôn ngữ nó kết xuất. Vì phần đó được tải theo yêu cầu, head trở thành async:

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: async ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // Đường dẫn cho tuyến đường này

    const metaContent = await getIntlayerAsync("app", locale);

    return {
      links: [
        // Liên kết chính tắc: Trỏ đến trang được bản địa hóa hiện tại
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Thông báo cho Google về tất cả các phiên bản được bản địa hóa
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Cho người dùng ở các ngôn ngữ không phù hợp
        // Xác định ngôn ngữ dự phòng mặc định (thường là ngôn ngữ chính của bạn)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});
      Nếu head đọc nhiều từ điển, hãy giải quyết chúng với Promise.all: chờ từng getIntlayerAsync trên dòng riêng của nó sẽ kết chuỗi các yêu cầu thay vì chạy chúng song song.

      Sự cân bằng: nhập động được phân giải trong khi head chạy, trên đường dẫn quan trọng của kết xuất tài liệu. Trên một tuyến đường lạnh, điều này làm trễ head một vài mili giây và có thể làm giảm nhẹ LCP.

      Giải quyết từ điển trong loader tuyến đường và đọc lại từ loaderData trong head. Loaders của các tuyến đường khớp chạy song song, và staleTime: Infinity cho TanStack Router biết rằng kết quả không bao giờ cũ, vì vậy phần theo ngôn ngữ được giải quyết một lần và được phục vụ từ bộ nhớ cache của router sau đó, để head đồng bộ.

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  // Được giải quyết song song với các tuyến đường khớp khác, không ngoài đường dẫn quan trọng của head
  loader: async ({ params }) => {
    const { locale = defaultLocale } = params;

    return { metaContent: await getIntlayerAsync("app", locale) };
  },
  // Từ điển không bao giờ thay đổi cho một ngôn ngữ nhất định: giải quyết phần một lần
  staleTime: Infinity,
  head: ({ params, loaderData }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // Đường dẫn cho tuyến đường này

    return {
      links: [
        // Liên kết chính tắc: Trỏ đến trang được bản địa hóa hiện tại
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Thông báo cho Google về tất cả các phiên bản được bản địa hóa
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Cho người dùng ở các ngôn ngữ không phù hợp
        // Xác định ngôn ngữ dự phòng mặc định (thường là ngôn ngữ chính của bạn)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: loaderData?.metaContent.title },
        {
          name: "description",
          content: loaderData?.metaContent.meta.description,
        },
      ],
    };
  },
});
      head có thể được gọi trước khi loader hoàn thành, vì vậy loaderData được gõ là có thể undefined. Giữ tùy chọn chaining, hoặc trả về tiêu đề dự phòng.

      Bạn giữ phần theo ngôn ngữ mà không phải trả giá của nó trên đường dẫn quan trọng của head. Giá là trải nghiệm nhà phát triển: nội dung phải được luồng rõ ràng từ loader đến head thông qua loaderData.

      Tôi nên chọn độ phân giải nào?

      Độ phân giải tĩnhĐộ phân giải độngĐộ phân giải động được lưu cache
      APIgetIntlayergetIntlayerAsync (v9.4+)getIntlayerAsync in loader (v9.4+)
      head signaturesynchronousasyncsynchronous, reads loaderData
      Locales shippedevery declared localerequested locale onlyrequested locale only
      Client navigationsnothing to resolvere-entered on every matchserved from the router cache
      Developer experiencesimplestone awaitcontent threaded through loaderData

    14. Truy xuất locale trong các server actions của bạn

      Bạn có thể muốn truy cập locale hiện tại từ bên trong các server actions hoặc API endpoints của mình. Bạn có thể thực hiện điều này bằng cách sử dụng helper getLocale từ intlayer.

      Đây là một ví dụ sử dụng các server functions của TanStack Start:

      src/routes/{-$locale}/index.tsx
      import { createServerFn } from "@tanstack/react-start";
import {
  getRequestHeader,
  getRequestHeaders,
} from "@tanstack/react-start/server";
import { getCookie, getIntlayer, getLocale } from "intlayer";

export const getLocaleServer = createServerFn().handler(async () => {
  const locale = await getLocale({
    // Lấy cookie từ request (mặc định: 'INTLAYER_LOCALE')
    getCookie: (name) => {
      const cookieString = getRequestHeader("cookie");

      return getCookie(name, cookieString);
    },
    // Lấy header từ request (mặc định: 'x-intlayer-locale')
    // Fallback sử dụng Accept-Language negotiation
    getHeader: (name) => getRequestHeader(name),
  });

  // Truy xuất một số nội dung sử dụng getIntlayerAsync()
  const content = getIntlayer("app", locale);

  return { locale, content };
});

    15. Quản lý trang không tìm thấy

      Khi người dùng truy cập một trang không tồn tại, bạn có thể hiển thị một trang không tìm thấy tùy chỉnh và tiền tố locale có thể ảnh hưởng đến cách trang không tìm thấy được kích hoạt.

      Hiểu về xử lý 404 của TanStack Router với tiền tố locale

      Trong TanStack Router, xử lý các trang 404 với các route đã được bản địa hóa yêu cầu một cách tiếp cận nhiều lớp:

      1. Route 404 chuyên dụng: Một route cụ thể để hiển thị giao diện 404
      2. Xác thực cấp route: Xác thực các tiền tố locale và chuyển hướng các tiền tố không hợp lệ đến 404
      3. Route catch-all: Bắt tất cả các đường dẫn không khớp trong phân đoạn locale
      src/routes/{-$locale}/404.tsx
      import { createFileRoute } from "@tanstack/react-router";

// Điều này tạo một tuyến đường /[locale]/404 chuyên dụng
// Nó được sử dụng cả như một tuyến đường trực tiếp và được nhập như một thành phần trong các tệp khác
export const Route = createFileRoute("/{-$locale}/404")({
  component: NotFoundComponent,
});

// Xuất riêng để có thể tái sử dụng trong notFoundComponent và các tuyến catch-all
export function NotFoundComponent() {
  return (
    <div>
      <h1>404</h1>
    </div>
  );
}
      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { validatePrefix } from "intlayer";
import { NotFoundComponent } from "./404";

export const Route = createFileRoute("/{-$locale}")({
  // beforeLoad chạy trước khi route được render (trên cả server và client)
  // Đây là nơi lý tưởng để xác thực tiền tố locale
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // validatePrefix kiểm tra xem locale có hợp lệ theo cấu hình intlayer của bạn không
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      // Tiền tố locale không hợp lệ - chuyển hướng đến trang 404 với tiền tố locale hợp lệ
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
  // notFoundComponent được gọi khi một route con không tồn tại
  // ví dụ: /en/trang-khong-ton-tai kích hoạt điều này trong layout /en
  notFoundComponent: NotFoundComponent,
});
      src/routes/{-$locale}/$.tsx
      import { createFileRoute } from "@tanstack/react-router";

import { NotFoundComponent } from "./404";

// Tuyến đường $ (splat/catch-all) khớp với bất kỳ đường dẫn nào không khớp với các tuyến đường khác
// ví dụ: /en/mot/duong/dan/sau/long/khong-hop-le
// Điều này đảm bảo TẤT CẢ các đường dẫn không khớp trong một locale hiển thị trang 404
// Nếu không có điều này, các đường dẫn sâu không khớp có thể hiển thị trang trống hoặc lỗi
export const Route = createFileRoute("/{-$locale}/$")({
  component: NotFoundComponent,
});

    16. Trích xuất nội dung các thành phần của bạn

      Tùy chọn

      isOptional={true}>

      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
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      Cập nhật vite.config.ts của bạn để bao gồm plugin intlayerCompiler:

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // Adds the compiler plugin
  ],
});
      bash
      npm run build # Hoặc npm run dev

    17. Pre-render & Generate Sitemap

      Intlayer đi kèm với một trình tạo sitemap tích hợp sẵn để giúp bạn tạo sitemap cho ứng dụng của mình một cách dễ dàng. Nó xử lý các tuyến đường đã được bản địa hóa và thêm các siêu dữ liệu cần thiết cho các công cụ tìm kiếm.

      Sitemap được tạo bởi Intlayer hỗ trợ namespace xhtml:link (Hreflang XML Extensions). Không giống như các trình tạo sitemap mặc định chỉ liệt kê các URL thô, Intlayer tự động tạo các liên kết hai chiều cần thiết giữa tất cả các phiên bản ngôn ngữ của một trang (ví dụ: /about, /about?lang=fr và /about?lang=es). Điều này đảm bảo các công cụ tìm kiếm lập chỉ mục chính xác và phục vụ phiên bản ngôn ngữ phù hợp cho đúng đối tượng.

      Để sử dụng nó, trước tiên bạn cần cấu hình vite.config.ts của mình để kích hoạt pre-rendering cho các route đã địa phương hóa của bạn và vô hiệu hóa việc tạo sitemap mặc định của TanStack Start.

      vite.config.ts
      import { localeFlatMap } from "intlayer";
// ... các import khác

export const pathList = ["", "/about", "/404"];

const localizedPages = localeFlatMap(({ urlPrefix }) =>
  pathList.map((path) => ({
    path: `${urlPrefix}${path}`,
    prerender: {
      enabled: true,
    },
  }))
);

export default defineConfig({
  plugins: [
    // ... các plugin khác
    tanstackStart({
      // ... cấu hình khác
      sitemap: {
        enabled: false,
      },
      prerender: {
        enabled: true,
        crawlLinks: false,
        concurrency: 10,
      },
      pages: localizedPages,
    }),
  ],
});

      Sau đó, tạo một route src/routes/sitemap[.]xml.ts sử dụng hàm generateSitemap:

      src/routes/sitemap[.]xml.ts
      import { createFileRoute } from "@tanstack/react-router";
import { generateSitemap } from "intlayer";

const SITE_URL = (
  import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
).replace(/\/$/, "");

export const Route = createFileRoute("/sitemap.xml")({
  server: {
    handlers: {
      GET: async () => {
        const sitemap = generateSitemap(
          [
            { path: "/", changefreq: "daily", priority: 1.0 },
            { path: "/about", changefreq: "monthly", priority: 0.8 },
          ],
          { siteUrl: SITE_URL }
        );

        return new Response(sitemap, {
          headers: { "Content-Type": "application/xml" },
        });
      },
    },
  },
});

    18. Cấu hình TypeScript

      Intlayer sử dụng module augmentation để tận dụng 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ự động tạo:

      tsconfig.json
      {
  // ... những cấu hình hiện tại của bạn
  include: [
    // ... những include hiện tại của bạn
    ".intlayer/**/*.ts", // Bao gồm các kiểu được tự động tạo
  ],
}

    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:

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

    VS Code Extension

    Để 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 Intlayer VS Code Extension chính thức.

    Cài đặt từ VS Code Marketplace

    Extension này cung cấp:

    • Autocompletion cho các khóa dịch.
    • Phát hiện lỗi real-time cho các bản dịch bị thiếu.
    • Inline previews của nội dung được dịch.
    • Quick actions để 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 extension, hãy tham khảo tài liệu Intlayer VS Code Extension.

    Đ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 ngoại hóa nội dung của bạn bằng CMS.

    Tài liệu tham khảo

    Các Câu Hỏi Thường Gặp

    TanStack Start không có lớp i18n riêng:

    • i18next / react-i18next và react-intl: các thư viện tải JSON ở runtime.
    • Intlayer: hỗ trợ SSR và SSG, khai báo cạnh component, kiểu dữ liệu TypeScript đầy đủ, dịch thuật AI và visual editor.

    Xem lý do chọn Intlayer.

    Ít hơn đáng kể so với các giải pháp dựa trên namespace, vì trang không bao giờ tải catalog mà nó không hiển thị. Compiler tại thời điểm build thay thế các lệnh gọi useIntlayer bằng chính xác các mục từ điển mà component sử dụng, và từ điển động chia phần còn lại theo từng locale, giảm kích thước bundle tới 50%. Xem tối ưu hóa bundle và benchmark.

    Có, thông qua hướng dẫn di chuyển hoặc adapter tương thích.

    Có. Plugin sync JSON giữ cho các tệp /messages/{locale}/{namespace}.json của bạn là nguồn sự thật duy nhất và tạo các từ điển Intlayer từ chúng theo cả hai hướng. Plugin sync PO làm điều tương tự cho các catalog gettext, và các tệp theo locale cho phép bạn chia nội dung theo ngôn ngữ thay vì nhóm các locale trong một tệp.

    Không. Chạy npx intlayer extract và Intlayer sẽ đọc các tệp nguồn của bạn, trích xuất các chuỗi dành cho người dùng và tạo tệp .content bên cạnh mỗi tệp, nhờ đó bạn xem lại diff thay vì sao chép chuỗi vào catalog thủ công.

    Để tự động hóa hoàn toàn, Intlayer Compiler thực hiện việc tương tự trong quá trình build: quét mã nguồn trên mỗi thay đổi, tạo từ điển và đồng bộ hóa với HMR.

    Hai giới hạn đáng lưu ý trước khi bạn bật compiler. Nó hoạt động bằng phân tích tĩnh, do đó các chuỗi chỉ tồn tại khi runtime, chẳng hạn như mã lỗi API hoặc các trường CMS, nằm ngoài phạm vi tiếp cận. Và nó phải phân biệt văn bản hiển thị cho người dùng với logic ứng dụng như className="active" hoặc mã trạng thái, điều này cần một vài chú thích trong một codebase lớn. Lệnh extract tránh cả hai điều này bằng cách giữ bạn luôn kiểm soát.

    Năm công cụ, tất cả đều là tùy chọn:

    • VS Code extension: nhảy từ khóa useIntlayer đến tệp nội dung khai báo nó, trích xuất nội dung từ component, và chạy build, fill, test, push và pull từ command palette hoặc tab Intlayer.
    • LSP server: trải nghiệm tương tự trong bất kỳ trình soạn thảo nào hỗ trợ LSP, với go to definition, xem trước giá trị bản dịch khi hover, tự động hoàn thành khóa, và cảnh báo khi khóa chưa được khai báo. Hỗ trợ cả các lệnh gọi i18next, react-i18next, next-intl và use-intl.
    • MCP server: cung cấp tài liệu và CLI Intlayer cho Cursor, VS Code, Claude Desktop, Claude Code và ChatGPT.
    • Agent skills: các kỹ năng chuyên biệt như intlayer-config, intlayer-cli và intlayer-content.
    • ESLint plugin: quy tắc no-raw-text phát hiện các chuỗi chưa được bản địa hóa.
    Next.js và Page RouterTanstack Start Solid