Penulis:
    Aymeric PINEAU
    Dibuat:2025-09-09Terakhir diperbarui:2026-08-25

    Terjemahkan situs web TanStack Start Anda menggunakan Intlayer | Internasionalisasi (i18n)

    Daftar Isi

    Panduan ini mendemonstrasikan cara mengintegrasikan Intlayer untuk internasionalisasi yang mulus dalam proyek TanStack Start dengan routing yang mendukung locale, dukungan TypeScript, dan praktik pengembangan modern.

    Mengapa Intlayer dibandingkan alternatif?

    Dibandingkan dengan solusi utama seperti react-i18next atau use-intl, atau paraglide, Intlayer adalah solusi yang hadir dengan pengoptimalan terintegrasi seperti:

    Intlayer sepenuhnya dioptimalkan untuk TanStack Start, menyediakan perutean multibahasa, manajemen cookie, pembuatan peta situs, pemuatan konten dinamis, dan semua fitur yang diperlukan untuk meningkatkan upaya internasionalisasi Anda (i18n).

    Daripada memuat file JSON berukuran besar ke halaman Anda, muat saja konten yang diperlukan. Intlayer membantu mengurangi ukuran bundle dan halaman Anda hingga 50%.

    Mencakup konten aplikasi Anda memfasilitasi pemeliharaan untuk aplikasi berskala besar. Anda dapat menduplikasi atau menghapus satu folder fitur tanpa beban mental untuk meninjau seluruh basis kode konten Anda. Selain itu, Intlayer diketik sepenuhnya untuk memastikan keakuratan konten Anda.

    Menempatkan konten bersama mengurangi konteks yang diperlukan dengan Model Bahasa Besar (LLM). Intlayer juga dilengkapi dengan serangkaian alat, seperti CLI untuk menguji terjemahan yang hilang,LSP, MCP, dan agent skills, untuk menjadikan pengalaman pengembang (DX) lebih lancar bagi agen AI.

    Gunakan otomatisasi untuk menerjemahkan dalam saluran CI/CD Anda menggunakan LLM pilihan Anda dengan biaya penyedia AI Anda. Intlayer juga menawarkan compiler untuk mengotomatiskan ekstraksi konten, serta platform web untuk membantu menerjemahkan di latar belakang.

    Menghubungkan file JSON berukuran besar ke komponen dapat menyebabkan masalah kinerja dan reaktivitas. Intlayer mengoptimalkan pemuatan konten Anda pada waktu pembuatan.

    Lebih dari sekedar solusi i18n, Intlayer menyediakan editor visual yang dihosting sendiri dan CMS lengkap untuk membantu Anda mengelola konten multibahasa secara real-time, membuat kolaborasi dengan penerjemah, copywriter, dan anggota tim lainnya menjadi lancar. Konten dapat disimpan secara lokal dan/atau jarak jauh.

    Panduan Langkah-demi-Langkah untuk Mengatur Intlayer dalam Aplikasi TanStack Start

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

    Lihat Template Aplikasi di GitHub.

    1. Buat Proyek

      Mulailah dengan membuat proyek TanStack Start baru dengan mengikuti panduan Memulai proyek baru di situs web TanStack Start.

    2. Pasang Paket Intlayer

      Pasang paket yang diperlukan menggunakan manajer paket pilihan Anda:

      bash
      npx intlayer init --interactive
      flag --interactive bersifat opsional. Gunakan intlayer-cli init jika Anda adalah agen AI.
      Perintah ini akan mendeteksi lingkungan Anda dan menginstal paket yang diperlukan. Misalnya:
      bash
      npm install intlayer react-intlayer
npm install vite-intlayer --save-dev

      • intlayer

        Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpiler, dan perintah CLI.

      • react-intlayer Paket yang mengintegrasikan Intlayer dengan aplikasi React. Ini menyediakan context provider dan hook untuk internasionalisasi React.

      • vite-intlayer Termasuk plugin Vite untuk mengintegrasikan Intlayer dengan Vite bundler, serta middleware untuk mendeteksi locale yang disukai pengguna, mengelola cookie, dan menangani pengalihan URL.

    3. Konfigurasi proyek Anda

      Buat file konfigurasi untuk mengonfigurasi bahasa aplikasi Anda:

      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;
      Melalui file konfigurasi ini, Anda dapat mengatur URL yang dilokalkan, pengalihan middleware, nama cookie, lokasi dan ekstensi deklarasi konten Anda, menonaktifkan log Intlayer di konsol, dan banyak lagi. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.

    4. Integrasikan Intlayer dalam Konfigurasi Vite Anda

      Tambahkan plugin intlayer ke dalam konfigurasi Anda:

      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() digunakan untuk mengintegrasikan Intlayer dengan Vite. Ini memastikan pembuatan file deklarasi konten dan memantaunya dalam mode pengembangan. Plugin ini mendefinisikan variabel lingkungan Intlayer di dalam aplikasi Vite. Selain itu, ini menyediakan alias untuk mengoptimalkan kinerja.

    5. Buat Layout Root

      Konfigurasikan layout root Anda untuk mendukung internasionalisasi dengan menggunakan useParams untuk mendeteksi locale saat ini dan mengatur atribut lang dan dir pada tag 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. Buat Layout Locale

      Buat layout yang menangani awalan locale dan melakukan validasi.

      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;

    // Validasi awalan locale
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
});
      Di sini, {-$locale} adalah parameter rute dinamis yang digantikan dengan locale saat ini. Notasi ini membuat slot bersifat opsional, memungkinkannya bekerja dengan mode perutean seperti 'prefix-no-default' dll.

      Sadari bahwa slot ini dapat menyebabkan masalah jika Anda menggunakan beberapa segmen dinamis dalam rute yang sama (misalnya, /{-$locale}/other-path/$anotherDynamicPath/...). Untuk mode 'prefix-all', Anda mungkin lebih suka mengganti slot menjadi $locale sebagai gantinya. Untuk mode 'no-prefix' atau 'search-params', Anda dapat menghapus slot sepenuhnya.

    7. Deklarasikan Konten Anda

      Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

      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 dengan TanStack Router",
      }),
    },
  },
  key: "app",
} satisfies Dictionary;

export default appContent;
      Deklarasi konten Anda dapat ditentukan di mana saja dalam aplikasi Anda segera setelah mereka dimasukkan ke dalam direktori contentDir (secara default, ./app). Dan cocok dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

    8. Buat Komponen dan Hook yang Menyadari Locale

      Buat komponen LocalizedLink untuk navigasi yang menyadari 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"]}
    />
  );
};

      Komponen ini memiliki dua tujuan:

      • Menghapus awalan {-$locale} yang tidak perlu dari URL.
      • Menyuntikkan parameter locale ke dalam URL untuk memastikan pengguna langsung diarahkan ke rute yang terlokalisasi.

      Kemudian kita dapat membuat hook useLocalizedNavigate untuk navigasi secara terprogram:

      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. Manfaatkan Intlayer di Halaman Anda

      Gunakan useIntlayer secara default: ini cara yang direkomendasikan untuk membaca konten di dalam komponen, dan compiler meresolusinya ke locale yang sedang dirender. Gunakan getIntlayer / getIntlayerAsync hanya di luar pohon React: head rute, loader, dan server function.

      Akses kamus konten Anda di seluruh aplikasi Anda:

      Halaman Beranda Terlokalisasi

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

      Jika Anda ingin menggunakan konten Anda dalam atribut string, seperti alt, title, href, aria-label, dll., Anda dapat menggunakan nilai dari fungsi, seperti:

      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)}" />
      Untuk mempelajari lebih lanjut tentang hook useIntlayer, lihat dokumentasi.

    10. Buat Komponen Locale Switcher

      Buat komponen untuk memungkinkan pengguna mengubah bahasa:

      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 - misalnya FR */}
              {localeEl}
            </span>
            <span>
              {/* Bahasa dalam Locale-nya sendiri - misalnya Français */}
              {getLocaleName(localeEl, locale)}
            </span>
            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
              {/* Bahasa dalam Locale saat ini - misalnya Francés dengan locale saat ini diatur ke Locales.SPANISH */}
              {getLocaleName(localeEl)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Bahasa dalam Bahasa Inggris - misalnya French */}
              {getLocaleName(localeEl, Locales.ENGLISH)}
            </span>
          </LocalizedLink>
        </li>
      ))}
    </ol>
  );
};
      Untuk mempelajari lebih lanjut tentang hook useLocale, lihat dokumentasi.

    11. Manajemen Atribut HTML

      Seperti yang terlihat di Step 5, Anda dapat mengelola atribut lang dan dir dari tag html menggunakan useParams di komponen root Anda. Ini memastikan bahwa atribut yang benar ditetapkan di server dan klien.

      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. Tambahkan middleware

      Anda juga dapat menggunakan intlayerProxy untuk menambahkan routing sisi server ke aplikasi Anda. Plugin ini akan secara otomatis mendeteksi locale saat ini berdasarkan URL dan menetapkan cookie locale yang sesuai. Jika tidak ada locale yang ditentukan, plugin akan menentukan locale yang paling sesuai berdasarkan preferensi bahasa browser pengguna. Jika tidak ada locale yang terdeteksi, plugin akan mengalihkan ke locale default.

      Perhatikan bahwa untuk menggunakan intlayerProxy dalam produksi, Anda perlu memindahkan paket vite-intlayer dari devDependencies ke dependencies.
      Sejak Intlayer v9, intlayerProxy() dikemas langsung ke dalam plugin intlayer() dan diaktifkan secara default melalui opsi routing.enableProxy (true secara default). Mendaftarnya secara terpisah seperti yang ditunjukkan di bawah ini sekarang bersifat opsional: ini disimpan untuk kompatibilitas backward dan untuk setup yang perlu mengontrol urutan plugin. Atur routing.enableProxy: false untuk tidak memilih. Lihat catatan rilis 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. Internasionalisasi Metadata Anda

      getIntlayer menyelesaikan secara sinkron terhadap kamus merged, yang memegang setiap locale yang dideklarasikan. head tetap sinkron dan tidak ada yang diharapkan, tetapi seluruh kamus multilingua ditarik ke dalam chunk rute yang dikirim ke browser.

      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 = "/"; // Path untuk rute ini

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

    return {
      links: [
        // Link canonical: Menunjuk ke halaman terlokalisasi saat ini
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Beritahu Google tentang semua versi terlokalisasi
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Untuk pengguna dalam bahasa yang tidak cocok
        // Tentukan locale fallback default (biasanya bahasa utama Anda)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});

      Terbaik untuk kamus metadata kecil, beberapa locale, atau saat prototyping.

      getIntlayerAsync (tersedia dari v9.4) berperilaku seperti getIntlayer, tetapi plugin build mengarahkannya ke chunk per-locale di .intlayer/dynamic_dictionaries/ bukan kamus merged. Halaman karenanya hanya mengirim locale yang ditampilkannya. Karena chunk itu dimuat sesuai permintaan, head menjadi 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 = "/"; // Path untuk rute ini

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

    return {
      links: [
        // Link canonical: Menunjuk ke halaman terlokalisasi saat ini
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Beritahu Google tentang semua versi terlokalisasi
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Untuk pengguna dalam bahasa yang tidak cocok
        // Tentukan locale fallback default (biasanya bahasa utama Anda)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});
      Jika head membaca beberapa kamus, selesaikan dengan Promise.all: menunggu setiap getIntlayerAsync pada baris sendiri merantai permintaan alih-alih menjalankannya secara paralel.

      Tradeoff: impor dinamis diselesaikan saat head berjalan, di jalur penting render dokumen. Pada rute dingin ini menunda head selama beberapa milidetik dan dapat sedikit merusak LCP.

      Selesaikan kamus di route loader dan baca kembali dari loaderData di head. Loader dari rute yang cocok berjalan secara paralel, dan staleTime: Infinity memberi tahu TanStack Router bahwa hasil tidak pernah basi, jadi chunk per-locale diselesaikan sekali dan disajikan dari cache router setelahnya, meninggalkan head sinkron.

      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,
  // Diselesaikan secara paralel dengan rute yang cocok lainnya, lepas dari jalur penting head
  loader: async ({ params }) => {
    const { locale = defaultLocale } = params;

    return { metaContent: await getIntlayerAsync("app", locale) };
  },
  // Kamus tidak pernah berubah untuk locale tertentu: selesaikan chunk sekali
  staleTime: Infinity,
  head: ({ params, loaderData }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // Path untuk rute ini

    return {
      links: [
        // Link canonical: Menunjuk ke halaman terlokalisasi saat ini
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Beritahu Google tentang semua versi terlokalisasi
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Untuk pengguna dalam bahasa yang tidak cocok
        // Tentukan locale fallback default (biasanya bahasa utama Anda)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: loaderData?.metaContent.title },
        {
          name: "description",
          content: loaderData?.metaContent.meta.description,
        },
      ],
    };
  },
});
      head dapat dipanggil sebelum loader settles, jadi loaderData diketik sebagai kemungkinan undefined. Pertahankan rantai opsional, atau kembalikan judul fallback.

      Anda menyimpan chunk per-locale tanpa membayar biayanya di jalur penting head. Harganya adalah pengalaman pengembang: konten harus dithread secara eksplisit dari loader ke head melalui loaderData.

      Resolusi mana yang harus saya pilih?

      Static resolution Dynamic resolution Cached dynamic resolution
      API getIntlayer getIntlayerAsync (v9.4+) getIntlayerAsync in loader (v9.4+)
      head signature synchronous async synchronous, reads loaderData
      Locales shipped every declared locale requested locale only requested locale only
      Client navigations nothing to resolve re-entered on every match served from the router cache
      Developer experience simplest one await content threaded through loaderData

    14. Ambil locale di server actions Anda

      Anda mungkin ingin mengakses locale saat ini dari dalam server actions atau API endpoints Anda. Anda dapat melakukan ini menggunakan helper getLocale dari intlayer.

      Berikut adalah contoh menggunakan TanStack Start's server functions:

      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({
    // Ambil cookie dari request (default: 'INTLAYER_LOCALE')
    getCookie: (name) => {
      const cookieString = getRequestHeader("cookie");

      return getCookie(name, cookieString);
    },
    // Ambil header dari request (default: 'x-intlayer-locale')
    // Fallback menggunakan negosiasi Accept-Language
    getHeader: (name) => getRequestHeader(name),
  });

  // Ambil beberapa konten menggunakan getIntlayerAsync()
  const content = getIntlayer("app", locale);

  return { locale, content };
});

    15. Kelola halaman tidak ditemukan

      Ketika seorang pengguna mengunjungi halaman yang tidak ada, Anda dapat menampilkan halaman tidak ditemukan yang disesuaikan dan awalan locale dapat mempengaruhi cara halaman tidak ditemukan dipicu.

      Memahami Penanganan 404 TanStack Router dengan Awalan Locale

      Di TanStack Router, menangani halaman 404 dengan rute yang dilokalisasi memerlukan pendekatan berlapis:

      1. Rute 404 khusus: Rute khusus untuk menampilkan UI 404
      2. Validasi tingkat rute: Memvalidasi awalan locale dan mengalihkan yang tidak valid ke 404
      3. Rute catch-all: Menangkap setiap jalur yang tidak cocok dalam segmen locale
      src/routes/{-$locale}/404.tsx
      import { createFileRoute } from "@tanstack/react-router";

// Ini membuat rute /[locale]/404 khusus
// Ini digunakan baik sebagai rute langsung maupun diimpor sebagai komponen di file lain
export const Route = createFileRoute("/{-$locale}/404")({
  component: NotFoundComponent,
});

// Diekspor secara terpisah sehingga dapat digunakan kembali dalam notFoundComponent dan rute 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 berjalan sebelum rute merender (di server maupun klien)
  // Ini adalah tempat yang ideal untuk memvalidasi awalan locale
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // validatePrefix memeriksa apakah locale valid sesuai dengan konfigurasi intlayer Anda
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      // Awalan locale tidak valid - alihkan ke halaman 404 dengan awalan locale yang valid
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
  // notFoundComponent dipanggil ketika rute anak tidak ada
  // misal, /en/non-existent-page memicu ini dalam layout /en
  notFoundComponent: NotFoundComponent,
});
      src/routes/{-$locale}/$.tsx
      import { createFileRoute } from "@tanstack/react-router";

import { NotFoundComponent } from "./404";

// Rute $ (splat/catch-all) cocok dengan jalur mana pun yang tidak cocok dengan rute lain
// misal, /en/some/deeply/nested/invalid/path
// Ini memastikan SEMUA jalur yang tidak cocok dalam suatu locale menampilkan halaman 404
// Tanpa ini, jalur dalam yang tidak cocok mungkin menampilkan halaman kosong atau kesalahan
export const Route = createFileRoute("/{-$locale}/$")({
  component: NotFoundComponent,
});

    16. Ekstrak konten komponen Anda

      Opsional

      isOptional={true}>

      Jika Anda memiliki basis kode yang ada, mengubah ribuan file bisa memakan waktu lama.

      Untuk memudahkan proses ini, Intlayer mengusulkan compiler / extractor untuk mengubah komponen Anda dan mengekstrak kontennya.

      Untuk mengaturnya, Anda dapat menambahkan bagian compiler di file intlayer.config.ts Anda:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Sisa konfigurasi Anda
  compiler: {
    /**
     * Menunjukkan apakah compiler harus diaktifkan.
     */
    enabled: true,

    /**
     * Menentukan jalur file output
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Menunjukkan apakah komponen harus disimpan setelah diubah. Dengan begitu, compiler dapat dijalankan satu kali saja untuk mengubah aplikasi, lalu dapat dihapus.
     */
    saveComponents: false,

    /**
     * Prefiks kunci kamus
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Jalankan extractor untuk mengubah komponen Anda dan mengekstrak kontennya

      bash
      npx intlayer extract
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      Perbarui vite.config.ts Anda untuk menyertakan 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 # Atau npm run dev

    17. Pre-render & Generate Sitemap

      Intlayer dilengkapi dengan pembuat sitemap bawaan untuk membantu Anda membuat sitemap untuk aplikasi Anda dengan mudah. Ini menangani rute yang dilokalisasi dan menambahkan metadata yang diperlukan untuk mesin pencari.

      Sitemap yang dihasilkan oleh Intlayer mendukung namespace xhtml:link (Hreflang XML Extensions). Berbeda dengan pembuat sitemap default yang hanya menampilkan URL mentah, Intlayer secara otomatis membuat tautan dua arah yang diperlukan antara semua versi bahasa dari sebuah halaman (misalnya, /about, /about?lang=fr, dan /about?lang=es). Ini memastikan mesin pencari dengan benar mengindeks dan melayani versi bahasa yang tepat kepada audiens yang tepat.

      Untuk menggunakannya, pertama-tama Anda perlu mengonfigurasi vite.config.ts Anda untuk mengaktifkan pre-rendering untuk rute terlokalisasi Anda dan menonaktifkan pembuatan sitemap TanStack Start default.

      vite.config.ts
      import { localeFlatMap } from "intlayer";
// ... import lainnya

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

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

export default defineConfig({
  plugins: [
    // ... plugin lainnya
    tanstackStart({
      // ... konfigurasi lainnya
      sitemap: {
        enabled: false,
      },
      prerender: {
        enabled: true,
        crawlLinks: false,
        concurrency: 10,
      },
      pages: localizedPages,
    }),
  ],
});

      Kemudian, buat rute src/routes/sitemap[.]xml.ts yang menggunakan fungsi 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. Konfigurasi TypeScript

      Intlayer menggunakan module augmentation untuk mendapatkan keuntungan dari TypeScript dan membuat codebase Anda lebih kuat.

      Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan secara otomatis:

      tsconfig.json
      {
  // ... konfigurasi yang sudah ada
  include: [
    // ... include yang sudah ada
    ".intlayer/**/*.ts", // Sertakan tipe yang dibuat secara otomatis
  ],
}

    Konfigurasi Git

    Disarankan untuk mengabaikan file yang dihasilkan oleh Intlayer. Ini memungkinkan Anda menghindari melakukan commit ke repositori Git Anda.

    Untuk melakukan ini, Anda dapat menambahkan instruksi berikut ke file .gitignore Anda:

    .gitignore
    # Abaikan file yang dihasilkan oleh Intlayer
.intlayer

    Ekstensi VS Code

    Untuk meningkatkan pengalaman pengembangan Anda dengan Intlayer, Anda dapat menginstal Intlayer VS Code Extension resmi.

    Instal dari VS Code Marketplace

    Ekstensi ini menyediakan:

    • Autocompletion untuk kunci terjemahan.
    • Deteksi kesalahan real-time untuk terjemahan yang hilang.
    • Pratinjau inline dari konten yang diterjemahkan.
    • Tindakan cepat untuk dengan mudah membuat dan memperbarui terjemahan.

    Untuk detail lebih lanjut tentang cara menggunakan ekstensi, lihat dokumentasi Intlayer VS Code Extension.

    Lanjutkan Lebih Jauh

    Untuk melanjutkan lebih jauh, Anda dapat menerapkan editor visual atau mengekstensikan konten Anda menggunakan CMS.

    Referensi Dokumentasi

    Pertanyaan yang Sering Diajukan

    TanStack Start tidak memiliki lapisan i18n sendiri:

    • i18next / react-i18next dan react-intl: library dengan pemuatan JSON di runtime.
    • Intlayer: dukungan SSR dan SSG, deklarasi di sebelah komponen, typing TypeScript lengkap, terjemahan AI, dan visual editor.

    Lihat mengapa Intlayer.

    Jauh lebih sedikit daripada solusi berbasis namespace, karena halaman tidak pernah mengunduh katalog yang tidak di-render. Kompilator build time mengganti panggilan useIntlayer dengan entri kamus persis yang digunakan komponen, dan kamus dinamis membagi sisanya per locale, mengurangi bundle hingga 50%. Lihat optimasi bundle dan benchmark.

    Ya, melalui panduan migrasi atau adapter kompatibilitas.

    Ya. Plugin sync JSON menjaga file /messages/{locale}/{namespace}.json Anda sebagai sumber kebenaran dan menghasilkan kamus Intlayer darinya, di kedua arah. Plugin sync PO melakukan hal yang sama untuk katalog gettext, dan file per locale memungkinkan Anda membagi konten berdasarkan bahasa daripada mengelompokkan lokal dalam satu file.

    Tidak. Jalankan npx intlayer extract dan Intlayer membaca file Anda, mengeluarkan string yang dihadapi pengguna, dan menulis file .content di sebelah masing-masing, sehingga Anda meninjau diff alih-alih menyalin string ke dalam katalog satu per satu.

    Untuk proses otomatis penuh, Intlayer Compiler melakukan hal yang sama saat build time: memindai kode pada setiap perubahan, menghasilkan kamus, dan menyinkronkannya dengan HMR.

    Dua batasan perlu diketahui sebelum Anda mengaktifkan compiler. Ini bekerja dengan analisis statis, jadi string yang hanya ada saat runtime, seperti kode kesalahan API atau field CMS, tetap berada di luar jangkauan. Dan ini harus membedakan teks yang dilihat pengguna dari logika aplikasi seperti className="active" atau kode status, yang memerlukan beberapa anotasi di basis kode yang besar. Perintah extract menghindari keduanya dengan menjaga Anda tetap memegang kendali.

    Lima bagian, semuanya opsional:

    • Ekstensi VS Code: lompat dari kunci useIntlayer ke file konten yang mendeklarasikannya, ekstrak konten dari komponen, dan jalankan build, fill, test, push dan pull dari command palette atau tab Intlayer.
    • Server LSP: pengalaman yang sama di editor mana pun yang mendukung LSP, dengan go to definition, hover preview dari nilai terjemahan, autocompletion kunci, dan peringatan ketika kunci tidak dideklarasikan. Ini juga menyelesaikan panggilan i18next, react-i18next, next-intl dan use-intl.
    • Server MCP: mengekspos dokumentasi Intlayer dan CLI ke Cursor, VS Code, Claude Desktop, Claude Code dan ChatGPT.
    • Agent skills: keahlian terfokus seperti intlayer-config, intlayer-cli dan intlayer-content.
    • Plugin ESLint: aturan no-raw-text menandai string hardcoded.
    CompilerTanstack Start Solid