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.

Panduan ini fokus pada frontend routing. Untuk routing fs-routes, lihat panduan Intlayer with React Router v7 File-System Routes.

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:

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

VideoKode (berbasis konfigurasi)Kode (rute sistem file)Demo (berbasis konfigurasi)

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-react-router-v7.vercel.app

Open embedded page in fullscreen

See the Config-Based Routing Template or File-System Routes Template on GitHub.

1. 1

   Pasang Dependencies

   Pasang paket yang diperlukan menggunakan manajer paket pilihan Anda:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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

   Salin konten

   Salin kode

   Salin kode ke clipboard

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

   • 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.

2. 2

   Konfigurasi proyek Anda

   Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

   intlayer.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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.

3. 3

   Integrasikan Intlayer dalam Konfigurasi Vite Anda

   Tambahkan plugin intlayer ke dalam konfigurasi Anda:

   vite.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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.

4. 4

   Konfigurasikan Rute React Router v7

   Config-based routingFile-system routes

   Atur konfigurasi routing Anda dengan rute yang mendukung lokal:

   app/routes.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { layout, route, type RouteConfig } from "@react-router/dev/routes";
   
   export default [
     route("/:locale?", "routes/page.tsx"), // Halaman beranda yang dilokalkan
     route("/:locale?/about", "routes/about/page.tsx"), // Halaman about yang dilokalkan
   ] satisfies RouteConfig;
   

   Set up your routing configuration to use file-system based routes with flatRoutes:

   app/routes.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { RouteConfig } from "@react-router/dev/routes";
   import { flatRoutes } from "@react-router/fs-routes";
   import { configuration } from "intlayer";
   
   const routes: RouteConfig = flatRoutes({
     // Ignore content declaration files from being treated as routes
     ignoredRouteFiles: configuration.content.fileExtensions.map(
       (fileExtension) => `**/*${fileExtension}`
     ),
   });
   
   export default routes;
   

   The flatRoutes function from @react-router/fs-routes enables file-system based routing, where the file structure in the routes/ directory determines your application's routes. The ignoredRouteFiles option ensures that Intlayer content declaration files (.content.ts, etc.) are not treated as route files.

5. 5

   Buat Komponen Layout

   Atur layout root Anda dan layout spesifik lokal:

   Layout Root

   app/root.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

6. 6

   Deklarasikan Konten Anda

   Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

   app/routes/[lang]/page.content.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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,md,mdx,yaml,yml}).

   Could be placed in app/routes/($locale)._index.content.ts in case of using file-system based routing.

   Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

7. 7

   Buat Komponen yang Menyadari Locale

   Buat komponen LocalizedLink untuk navigasi yang menyadari locale:

   app/components/localized-link.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

8. 8

   Gunakan Intlayer di Halaman Anda

   Akses kamus konten Anda di seluruh aplikasi:

   Halaman Beranda yang Dilokalkan

   Config-based routingFile-system routes

   app/routes/page.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   app/routes/($locale)._index.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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/($locale)._index";
   
   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.

9. 9

   Buat Komponen Locale Switcher

   Buat komponen untuk memungkinkan pengguna mengganti bahasa:

   Config-based routingFile-system routes

   app/components/locale-switcher.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     defaultLocale,
   } from "intlayer";
   import { 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, setLocale } = 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)}
               reloadDocument // Reload the page to apply the new locale
               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={defaultLocale}>
                 {/* Bahasa dalam Bahasa Inggris - misalnya French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   app/components/locale-switcher.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     defaultLocale,
   } from "intlayer";
   import { 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, setLocale } = 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)}
               reloadDocument // Reload the page to apply the new locale
               to={getLocalizedUrl(pathWithoutLocale, localeItem)}
             >
               <span>
                 {/* Locale - e.g. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Language in its own Locale - e.g. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Language in current Locale - e.g. Francés with current locale set to Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={defaultLocale}>
                 {/* Language in English - e.g. French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   Untuk mempelajari lebih lanjut tentang hook useLocale, lihat dokumentasi.

10. 10

    Tambahkan Manajemen Atribut HTML

    Buat hook untuk mengelola atribut lang dan dir HTML:

    app/hooks/useI18nHTMLAttributes.tsx

    Salin konten

    Salin kode

    Salin kode ke clipboard

    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

    Salin konten

    Salin kode

    Salin kode ke clipboard

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

11. 11

    Tambahkan middleware

    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 ke locale default.

    Perlu diketahui 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 tetap disimpan untuk kompatibilitas mundur dan untuk setup yang perlu mengontrol urutan plugin. Atur routing.enableProxy: false untuk tidak menggunakan fitur ini. Lihat catatan rilis v9.

    vite.config.ts

    Salin konten

    Salin kode

    Salin kode ke clipboard

    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react-swc";
    import { intlayer } from "vite-intlayer";
    
    // https://vitejs.dev/config/
    export default defineConfig({
      plugins: [
        react(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
      ],
    });
    

12. 12

    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

    Salin konten

    Salin kode

    Salin kode ke clipboard

    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;
    

    Perintah ekstrakCompiler Babel

    Jalankan extractor untuk mengubah komponen Anda dan mengekstrak kontennya

    bash

    Salin konten

    Salin kode

    Salin kode ke clipboard

    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

    Salin konten

    Salin kode

    Salin kode ke clipboard

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Salin konten

    Salin kode

    Salin kode ke clipboard

    npm run build # Atau npm run dev
    

Configure TypeScript

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

Ensure your TypeScript configuration includes the autogenerated types:

{
  // ... 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:

# 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.

Melangkah Lebih Jauh

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

Referensi Dokumentasi

• Dokumentasi Intlayer
• Dokumentasi React Router v7
• useIntlayer hook
• useLocale hook
• Deklarasi Konten
• Konfigurasi

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.

Pertanyaan yang Sering Diajukan