Penulis:
    Aymeric PINEAU
    Dibuat:2025-09-04Terakhir diperbarui:2026-06-23

    Terjemahkan situs web React Router v7 Anda menggunakan Intlayer | Internasionalisasi (i18n)

    Panduan ini menunjukkan cara mengintegrasikan Intlayer untuk internasionalisasi yang mulus dalam proyek React Router v7 dengan routing yang mendukung locale, dukungan TypeScript, dan praktik pengembangan modern.

    Untuk routing sisi klien, lihat panduan Intlayer dengan React Router v7.

    Table of Contents

    Mengapa Intlayer dibandingkan alternatif?

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

    Intlayer dioptimalkan untuk bekerja sempurna dengan React Router dengan menawarkan perutean sadar lokal, middleware untuk deteksi lokal, dan semua fitur yang diperlukan untuk penskalaan internasionalisasi (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 React Router v7 dengan Rute Berbasis Sistem File

    www.youtube.com
    ide.intlayer.org
    intlayer-react-router-v7.vercel.app

    See Application Template on GitHub.

  2. Install Dependencies

    Instal paket yang diperlukan menggunakan package manager pilihan Anda:

    bash
    npm install intlayer react-intlayer
npm install vite-intlayer --save-dev
npm install @react-router/fs-routes --save-dev
npx intlayer init
    • intlayer

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

    • react-intlayer Paket yang mengintegrasikan Intlayer dengan aplikasi React. Menyediakan context providers dan hooks untuk internasionalisasi React.

    • vite-intlayer Mencakup plugin Vite untuk mengintegrasikan Intlayer dengan Vite bundler, serta middleware untuk mendeteksi locale pilihan pengguna, mengelola cookies, dan menangani pengalihan URL.

    • @react-router/fs-routes Package yang mengaktifkan file-system based routing untuk React Router v7.

  3. Konfigurasi proyek Anda

    4. Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

    intlayer.config.ts
    import { type IntlayerConfig, 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 lainnya. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.

    1. Integrasikan Intlayer dalam Konfigurasi Vite Anda

      Tambahkan plugin intlayer ke dalam konfigurasi Anda:

      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [reactRouter(), intlayer()],
});
      Plugin Vite intlayer() digunakan untuk mengintegrasikan Intlayer dengan Vite. Plugin ini memastikan pembuatan file deklarasi konten dan memantau file tersebut dalam mode pengembangan. Plugin ini juga mendefinisikan variabel lingkungan Intlayer di dalam aplikasi Vite. Selain itu, plugin ini menyediakan alias untuk mengoptimalkan performa.

    2. Konfigurasikan Rute React Router v7

      Atur konfigurasi routing Anda dengan rute yang mendukung lokal:

      app/routes.ts
      import { layout, route, type RouteConfig } from "@react-router/dev/routes";

export default [
  layout("routes/layout.tsx", [
    route("/:lang?", "routes/page.tsx"), // Halaman beranda yang dilokalkan
    route("/:lang?/about", "routes/about/page.tsx"), // Halaman about yang dilokalkan
  ]),
] satisfies RouteConfig;
      Fungsi flatRoutes dari @react-router/fs-routes memungkinkan routing berbasis sistem file, di mana struktur file dalam direktori routes/ menentukan rute aplikasi Anda. Opsi ignoredRouteFiles memastikan bahwa file deklarasi konten Intlayer (.content.ts, dll.) tidak diperlakukan sebagai file rute.

    3. Buat Komponen Layout

      Dengan file-system routing, Anda menggunakan konvensi penamaan yang rata di mana titik (.) mewakili segmen path dan tanda kurung () menunjukkan segmen opsional.

      Atur layout root Anda dan layout spesifik lokal:

      Struktur File

      bash
      app/
├── root.tsx                         # Layout wrapper untuk locale routes
└──routes/
    ├── ($locale)._index.tsx         # Home page (/, /es, dll.)
    ├── ($locale)._index.content.ts  # Home page content
    ├── ($locale).about.tsx          # About page (/about, /es/about, dll.)
    └── ($locale).about.content.ts   # About page content

      Konvensi penamaan:

      • ($locale) - Optional dynamic segment untuk parameter locale
      • _layout - Layout route yang membungkus child routes
      • _index - Index route (renders di parent path)
      • . (dot) - Memisahkan path segments (contoh: ($locale).about → /:locale?/about)

      Komponen Layout

      app/root.tsx
      import { getLocaleFromPath } from "intlayer";
import { IntlayerProvider } from "react-intlayer";
import {
  isRouteErrorResponse,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
  useLoaderData,
} from "react-router";

import type { Route } from "./+types/root";

import "./app.css";

// ... Kode App, links dan ErrorBoundary yang tidak berubah

export async function loader({ request }: Route.LoaderArgs) {
  const locale = getLocaleFromPath(request.url);

  return { locale };
}

export function Layout({
  children,
}: { children: React.ReactNode } & Route.ComponentProps) {
  const data = useLoaderData<typeof loader>();
  const { locale } = data ?? {};

  return (
    <html lang={locale}>
      <head>
        <meta charSet="utf-8" />
        <meta content="width=device-width, initial-scale=1" name="viewport" />
        <Meta />
        <Links />
      </head>
      <body>
        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

      Layout Root

      app/components/localized-link.tsx
      import type { FC } from "react";

import { getLocalizedUrl, type LocalesValues } from "intlayer";
import { useLocale } from "react-intlayer";
import { Link, type LinkProps, type To } from "react-router";

const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);

export const locacalizeTo = (to: To, locale: LocalesValues): To => {
  if (typeof to === "string") {
    if (isExternalLink(to)) {
      return to;
    }

    return getLocalizedUrl(to, locale);
  }

  if (isExternalLink(to.pathname ?? "")) {
    return to;
  }

  return {
    ...to,
    pathname: getLocalizedUrl(to.pathname ?? "", locale),
  };
};

export const LocalizedLink: FC<LinkProps> = (props) => {
  const { locale } = useLocale();

  return <Link {...props} to={locacalizeTo(props.to, locale)} />;
};

      Halaman Beranda yang Dilokalkan

      app/routes/[lang]/page.tsx
      import { useIntlayer } from "react-intlayer";
import { LocalizedLink } from "~/components/localized-link";

export default function Page() {
  const { title, description, aboutLink } = useIntlayer("page");

  return (
    <div>
      <h1>{title}</h1>
      <p>{description}</p>
      <nav>
        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
      </nav>
    </div>
  );
}

    4. Deklarasikan Konten Anda

      Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan. Tempatkan file konten di samping file rute Anda:

      app/routes/($locale)._index.content.ts
      import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    title: t({
      id: "Selamat datang di React Router v7 + Intlayer",
      en: "Welcome to React Router v7 + Intlayer",
      es: "Bienvenido a React Router v7 + Intlayer",
      fr: "Bienvenue sur React Router v7 + Intlayer",
    }),
    description: t({
      id: "Buat aplikasi multibahasa dengan mudah menggunakan React Router v7 dan Intlayer.",
      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",
      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
    }),
    aboutLink: t({
      id: "Pelajari Tentang Kami",
      en: "Learn About Us",
      es: "Aprender Sobre Nosotros",
      fr: "En savoir plus sur nous",
    }),
  },
} satisfies Dictionary;

export default pageContent;
      app/routes/($locale).about.content.ts
      import { t, type Dictionary } from "intlayer";

const aboutContent = {
  key: "about",
  content: {
    title: t({
      id: "Tentang Kami",
      en: "About Us",
      es: "Sobre Nosotros",
      fr: "À propos de nous",
    }),
    content: t({
      id: "Ini adalah konten halaman tentang kami.",
      en: "This is the about page content.",
      es: "Este es el contenido de la página de información.",
      fr: "Ceci est le contenu de la page à propos.",
    }),
    homeLink: t({
      id: "Beranda",
      en: "Home",
      es: "Inicio",
      fr: "Accueil",
    }),
  },
} satisfies Dictionary;

export default aboutContent;
      Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda asalkan disertakan 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 mempelajari lebih lanjut tentang hook useIntlayer, lihat dokumentasi.
      Jika aplikasi Anda sudah ada, Anda dapat menggunakan Intlayer Compiler secara kombinasi dengan perintah extract untuk mengonversi ribuan komponen dalam satu detik.

    5. Buat Komponen yang Menyadari Locale

      Buat komponen LocalizedLink untuk navigasi yang aware terhadap locale:

      app/components/localized-link.tsx
      import type { FC } from "react";

import { getLocalizedUrl, type LocalesValues } from "intlayer";
import { useLocale } from "react-intlayer";
import { Link, type LinkProps, type To } from "react-router";

const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);

export const locacalizeTo = (to: To, locale: LocalesValues): To => {
  if (typeof to === "string") {
    if (isExternalLink(to)) {
      return to;
    }

    return getLocalizedUrl(to, locale);
  }

  if (isExternalLink(to.pathname ?? "")) {
    return to;
  }

  return {
    ...to,
    pathname: getLocalizedUrl(to.pathname ?? "", locale),
  };
};

export const LocalizedLink: FC<LinkProps> = (props) => {
  const { locale } = useLocale();

  return <Link {...props} to={locacalizeTo(props.to, locale)} />;
};

      Jika Anda ingin menavigasi ke rute yang dilokalisasi, Anda dapat menggunakan hook useLocalizedNavigate:

      app/hooks/useLocalizedNavigate.ts
      import { useLocale } from "react-intlayer";
import { type NavigateOptions, type To, useNavigate } from "react-router";

import { locacalizeTo } from "~/components/localized-link";

export const useLocalizedNavigate = () => {
  const navigate = useNavigate();
  const { locale } = useLocale();

  const localizedNavigate = (to: To, options?: NavigateOptions) => {
    const localedTo = locacalizeTo(to, locale);

    navigate(localedTo, options);
  };

  return localizedNavigate;
};

    6. Buat Komponen Locale Switcher

      Buat komponen untuk memungkinkan pengguna mengganti bahasa:

      app/components/locale-switcher.tsx
      import type { FC } from "react";

import {
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
  getPathWithoutLocale,
  Locales,
} from "intlayer";
import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";
import { Link, useLocation } from "react-router";

export const LocaleSwitcher: FC = () => {
  const { localeSwitcherLabel } = useIntlayer("locale-switcher");
  const { pathname } = useLocation();

  const { availableLocales, locale } = useLocale();

  const pathWithoutLocale = getPathWithoutLocale(pathname);

  return (
    <ol>
      {availableLocales.map((localeItem) => (
        <li key={localeItem}>
          <Link
            aria-current={localeItem === locale ? "page" : undefined}
            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
            onClick={() => setLocale(localeItem)}
            to={getLocalizedUrl(pathWithoutLocale, localeItem)}
          >
            <span>
              {/* Locale - misal FR */}
              {localeItem}
            </span>
            <span>
              {/* Bahasa dalam Locale-nya sendiri - misalnya Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Bahasa dalam Locale saat ini - misalnya Francés dengan locale saat ini disetel ke Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Bahasa dalam Bahasa Inggris - misalnya French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        </li>
      ))}
    </ol>
  );
};
      Untuk mempelajari lebih lanjut tentang hook useLocale, lihat dokumentasi.

    7. Tambahkan Manajemen Atribut HTML

      Buat hook untuk mengelola atribut lang dan dir HTML:

      app/hooks/useI18nHTMLAttributes.tsx
      import { 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]);
};

      Hook ini sudah digunakan dalam komponen layout (($locale)._layout.tsx) yang ditampilkan di Step 5.

      8. Kemudian gunakan di komponen root Anda:

      Anda juga dapat menggunakan intlayerProxy untuk menambahkan routing di 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 mengarahkan ulang ke locale default.

      Perhatikan bahwa untuk menggunakan intlayerProxy di production, Anda perlu memindahkan paket vite-intlayer dari devDependencies ke dependencies.
      Sejak Intlayer v9, intlayerProxy() digabungkan langsung ke dalam plugin intlayer() dan diaktifkan secara default melalui opsi routing.enableProxy (true secara default). Mendaftarkannya secara terpisah seperti yang ditunjukkan di bawah ini sekarang bersifat opsional — ini dipertahankan untuk kompatibilitas backward dan untuk setup yang perlu mengontrol urutan plugin. Atur routing.enableProxy: false untuk tidak menggunakannya. Lihat catatan rilis v9.
      app/routes/layout.tsx
      import { Outlet } from "react-router";
import { IntlayerProvider } from "react.intlayer";

import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // impor hook

export default function RootLayout() {
  useI18nHTMLAttributes(); // panggil hook

  return (
    <IntlayerProvider>
      <Outlet />
    </IntlayerProvider>
  );
}

    8. Ekstrak konten komponen Anda

      Opsional

      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

      9. </Steps>

      Configure TypeScript

      Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

      Ensure your TypeScript configuration includes the autogenerated types:

      tsconfig.json
      {
  // ... your existing configurations
  include: [
    // ... your existing includes
    ".intlayer/**/*.ts", // Include the auto-generated types
  ],
}

      Konfigurasi Git

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

      Untuk melakukannya, 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 Ekstensi Intlayer VS Code resmi.

      Pasang dari VS Code Marketplace

      Ekstensi ini menyediakan:

      • Autocompletion untuk kunci terjemahan.
      • Deteksi kesalahan secara 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 ini, lihat dokumentasi Ekstensi VS Code Intlayer.

      Melangkah Lebih Jauh

      Untuk melangkah lebih jauh, Anda dapat mengimplementasikan editor visual atau mengeksternalisasi konten Anda menggunakan CMS.

      Referensi Dokumentasi

      Panduan komprehensif ini menyediakan semua yang Anda butuhkan untuk mengintegrasikan Intlayer dengan React Router v7 guna aplikasi yang sepenuhnya diinternasionalkan dengan routing yang mengenali locale dan dukungan TypeScript.

      React Router v7Compiler