Creation:2025-09-04Last update:2026-05-06

    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.

    Table of Contents

    Apa itu Intlayer?

    Intlayer adalah pustaka internasionalisasi (i18n) open-source yang inovatif, dirancang untuk menyederhanakan dukungan multibahasa dalam aplikasi web modern.

    Dengan Intlayer, Anda dapat:

    • Mengelola terjemahan dengan mudah menggunakan kamus deklaratif di tingkat komponen.
    • Melokalkan metadata, rute, dan konten secara dinamis.
    • Memastikan dukungan TypeScript dengan tipe yang dihasilkan secara otomatis, meningkatkan autocompletion dan deteksi kesalahan.
    • Manfaatkan fitur canggih, seperti deteksi dan pergantian locale secara dinamis.
    • Aktifkan routing yang mendukung locale dengan sistem routing berbasis konfigurasi React Router v7.

    Panduan Langkah demi Langkah untuk Mengatur Intlayer dalam Aplikasi React Router v7

    Langkah 1: Pasang Dependencies

    Pasang paket yang diperlukan menggunakan manajer paket pilihan Anda:

    bash
    npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

    • intlayer

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

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

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

    Langkah 2: Konfigurasi proyek Anda

    Panduan Langkah demi Langkah untuk Mengatur Intlayer dalam Aplikasi React Router v7 dengan Rute Berbasis Sistem File

    www.youtube.com

    See Application Template on GitHub.

    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.

    Langkah 3: 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.

    Langkah 4: 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 [  route("/:lang?", "routes/page.tsx"), // Halaman beranda yang dilokalkan  route("/:lang?/about", "routes/about/page.tsx"), // Halaman about yang dilokalkan] satisfies RouteConfig;

    Langkah 5: Buat Komponen Layout

    Atur layout root Anda dan layout spesifik lokal:

    Layout Root

    app/root.tsx
    import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import {  data,  Meta,  Scripts,  ScrollRestoration,  useLoaderData,} from "react-router";import type { Route } from "./+types/root";// ... Unchanged App, links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) {  const locale = getLocaleFromPath(request.url);  if (!locale) {    throw data("Language not supported", { status: 404 });  }  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>  );}

    Langkah 6: Deklarasikan Konten Anda

    Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

    app/routes/[lang]/page.content.ts
    import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    title: t({      en: "Welcome to React Router v7 + Intlayer",      es: "Bienvenido a React Router v7 + Intlayer",      fr: "Bienvenue sur React Router v7 + Intlayer",    }),    description: t({      en: "Bangun aplikasi multibahasa dengan mudah menggunakan React Router v7 dan 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({      en: "Pelajari Tentang Kami",      es: "Aprender Sobre Nosotros",      fr: "En savoir plus sur nous",    }),    homeLink: t({      en: "Beranda",      es: "Inicio",      fr: "Accueil",    }),  },} satisfies Dictionary;export default pageContent;
    Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama sudah dimasukkan ke dalam direktori contentDir (secara default, ./app). Dan sesuai dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,cjs}).
    Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

    Langkah 7: Buat Komponen yang Menyadari Locale

    Buat komponen LocalizedLink untuk navigasi yang menyadari 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 sudah dilokalkan, 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;};

    Langkah 8: Gunakan Intlayer di Halaman Anda

    Akses kamus konten Anda di seluruh aplikasi:

    Halaman Beranda yang Dilokalkan

    app/routes/page.tsx
    import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/page";export const loader = ({ params }: Route.LoaderArgs) => {  const { locale } = params;  const { isValid } = validatePrefix(locale);  if (!isValid) {    throw data("Locale not supported", { status: 404 });  }};export const meta: Route.MetaFunction = ({ params }) => {  const content = getIntlayer("page", params.locale);  return [    { title: content.title },    { content: content.description, name: "description" },  ];};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>  );}
    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.

    Langkah 9: 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.

    Langkah 10: Tambahkan Manajemen Atribut HTML (Opsional)

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

    Kemudian gunakan di komponen root Anda:

    app/routes/layout.tsx
    import { Outlet } from "react-router";import { IntlayerProvider } from "react.intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // impor hookexport default function RootLayout() {  useI18nHTMLAttributes(); // panggil hook  return (    <IntlayerProvider>      <Outlet />    </IntlayerProvider>  );}

    (Opsional) Langkah 1 : Ekstrak konten komponen Anda

    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

    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  ],}

    Git Configuration

    It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

    To do this, you can add the following instructions to your .gitignore file:

    .gitignore
    # Ignore the files generated by Intlayer.intlayer

    VS Code Extension

    To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

    Install from the VS Code Marketplace

    This extension provides:

    • Autocompletion for translation keys.
    • Real-time error detection for missing translations.
    • Inline previews of translated content.
    • Quick actions to easily create and update translations.

    For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

    Go Further

    To go further, you can implement the visual editor or externalize your content using the CMS.

    Documentation References

    This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 for a fully internationalized application with locale-aware routing and TypeScript support.

    Langkah 11: Tambahkan middleware (Opsional)

    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 mengatur 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, maka akan mengarahkan ulang ke locale default.

    Perlu dicatat bahwa untuk menggunakan intlayerProxy di produksi, Anda perlu memindahkan paket vite-intlayer dari devDependencies ke dependencies.
    vite.config.ts
    import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    reactRouter(),    intlayer(),  ],});

    Konfigurasi TypeScript

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

    Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan secara otomatis:

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

    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.

    Vite dan React
    React Router v7 (fs-routes)