Creation:2024-12-06Last update:2026-05-31

    Menerjemahkan situs web Next.js 14 dan App Router Anda menggunakan Intlayer | Internasionalisasi (i18n)

    ide.intlayer.org

    Daftar Isi

    Mengapa Intlayer dibandingkan alternatif?

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

    Intlayer dioptimalkan untuk bekerja dengan Komponen Server untuk rendering yang efisien dan sepenuhnya kompatibel dengan Turbopack. Itu tidak memblokir rendering statis dan menawarkan middleware serta semua fitur yang diperlukan untuk penskalaan internasionalisasi (i18n).

    Intlayer kompatibel dengan Next.js 12, 13, 14, 15, dan 16. Jika Anda menggunakan Next.js Pages Router, Anda dapat merujuk ke [panduan] ini(/id/doc/environment/nextjs/next-with-page-router). Perutean lokal berguna untuk SEO, ukuran bundle, dan kinerja. Jika Anda tidak membutuhkannya, Anda dapat merujuk ke [panduan] ini(/id/doc/environment/nextjs/no-locale-path). Untuk Next.js 12, 13, 14, dan 15 dengan App Router, lihat [panduan] ini(/id/doc/environment/nextjs/14).

    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 skill, 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 Next.js

    Lihat Template Aplikasi di GitHub.

    1. Instalasi Dependensi

      Pasang paket yang diperlukan menggunakan npm:

      bash
      npm install intlayer next-intlayernpx intlayer init

      • intlayer

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

      • next-intlayer

        Paket yang mengintegrasikan Intlayer dengan Next.js. Paket ini menyediakan context providers dan hooks untuk internasionalisasi Next.js. Selain itu, paket ini juga menyertakan plugin Next.js untuk mengintegrasikan Intlayer dengan Webpack atau Turbopack, serta middleware untuk mendeteksi locale yang dipilih pengguna, mengelola cookie, dan menangani pengalihan URL.

    2. Konfigurasikan Proyek Anda

      Here is the final structure that we will make:

      bash
      .├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── middleware.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json
      If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

      Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Bahasa lain milik Anda
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

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. Integrasikan Intlayer dalam Konfigurasi Next.js Anda

      Konfigurasikan setup Next.js Anda untuk menggunakan Intlayer:

      next.config.mjs
      import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {};export default withIntlayer(nextConfig);
      Plugin Next.js withIntlayer() digunakan untuk mengintegrasikan Intlayer dengan Next.js. Plugin ini memastikan pembuatan file deklarasi konten dan memantau file tersebut dalam mode pengembangan. Ia mendefinisikan variabel lingkungan Intlayer dalam lingkungan Webpack atau Turbopack. Selain itu, plugin ini menyediakan alias untuk mengoptimalkan performa dan memastikan kompatibilitas dengan komponen server.

      Fungsi withIntlayer() adalah fungsi promise. Jika Anda ingin menggunakannya bersama plugin lain, Anda dapat menggunakan await. Contoh:

      tsx
      const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

    4. Konfigurasikan Middleware untuk Deteksi Locale

      Siapkan middleware untuk mendeteksi locale yang diinginkan pengguna:

      src/middleware.ts
      export { intlayerMiddleware as middleware } from "next-intlayer/middleware";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
      intlayerMiddleware digunakan untuk mendeteksi locale yang diinginkan pengguna dan mengarahkan mereka ke URL yang sesuai seperti yang ditentukan dalam konfigurasi. Selain itu, ini memungkinkan penyimpanan locale yang diinginkan pengguna dalam cookie.
      Sesuaikan parameter matcher agar sesuai dengan rute aplikasi Anda. Untuk detail lebih lanjut, lihat dokumentasi Next.js tentang konfigurasi matcher.
      Jika Anda perlu menggabungkan beberapa middleware bersama-sama (misalnya, intlayerMiddleware dengan autentikasi atau middleware kustom), Intlayer sekarang menyediakan helper yang disebut multipleMiddlewares.
      ts
      import {  multipleMiddlewares,  intlayerMiddleware,} from "next-intlayer/middleware";import { customMiddleware } from "@utils/customMiddleware";export const middleware = multipleMiddlewares([  intlayerMiddleware,  customMiddleware,]);

    5. Definisikan Rute Locale Dinamis

      Hapus semua isi dari RootLayout dan ganti dengan kode berikut:

      src/app/layout.tsx
      import type { PropsWithChildren, FC } from "react";
import "./globals.css";

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  // Anda masih dapat membungkus children dengan provider lain, seperti `next-themes`, `react-query`, `framer-motion`, dll.
  <>{children}</>
);

export default RootLayout;
      Membiarkan komponen RootLayout kosong memungkinkan untuk mengatur atribut lang dan dir pada tag <html>.

      Untuk mengimplementasikan routing dinamis, sediakan path untuk locale dengan menambahkan layout baru di direktori [locale] Anda:

      src/app/[locale]/layout.tsx
      import {
  type Next14LayoutIntlayer,
  IntlayerClientProvider,
} from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: Next14LayoutIntlayer = ({
  children,
  params: { locale },
}) => (
  <html lang={locale} dir={getHTMLTextDir(locale)}>
    <body className={inter.className}>
      <IntlayerClientProvider locale={locale}>
        {children}
      </IntlayerClientProvider>
    </body>
  </html>
);

export default LocaleLayout;
      Segmen path [locale] digunakan untuk menentukan locale. Contoh: /en-US/about akan merujuk ke en-US dan /fr/about ke fr.
      Pada tahap ini, Anda akan menemui error: Error: Missing <html> and <body> tags in the root layout.. Ini adalah hal yang diharapkan karena file /app/page.tsx tidak lagi digunakan dan dapat dihapus. Sebagai gantinya, segmen path [locale] akan mengaktifkan halaman /app/[locale]/page.tsx. Akibatnya, halaman akan dapat diakses melalui path seperti /en, /fr, /es di browser Anda. Untuk mengatur locale default sebagai halaman root, lihat pengaturan middleware pada langkah 4.

      Kemudian, implementasikan fungsi generateStaticParams di Layout aplikasi Anda.

      src/app/[locale]/layout.tsx
      export { generateStaticParams } from "next-intlayer"; // Baris untuk disisipkan

const LocaleLayout: Next14LayoutIntlayer = ({
  children,
  params: { locale },
}) => {
  /*... Sisa kode*/
};

export default LocaleLayout;
      generateStaticParams memastikan bahwa aplikasi Anda membangun terlebih dahulu halaman-halaman yang diperlukan untuk semua locale, mengurangi komputasi saat runtime dan meningkatkan pengalaman pengguna. Untuk detail lebih lanjut, lihat dokumentasi Next.js tentang generateStaticParams.

    6. Deklarasikan Konten Anda

      Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

      src/app/[locale]/page.content.ts
      import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        en: "Mulai dengan mengedit",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} 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, ./src). 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.

    7. Gunakan Konten dalam Kode Anda

      Akses kamus konten Anda di seluruh aplikasi Anda:

      src/app/[locale]/page.tsx
      import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type Next14PageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const Page: Next14PageIntlayer = ({ params: { locale } }) => {
  const content = useIntlayer("page", locale);

  return (
    <>
      <p>
        {content.getStarted.main}
        <code>{content.getStarted.pageLink}</code>
      </p>

      <IntlayerServerProvider locale={locale}>
        <ServerComponentExample />
        <ClientComponentExample />
      </IntlayerServerProvider>
    </>
  );
};

export default Page;
      • IntlayerClientProvider digunakan untuk menyediakan locale ke komponen sisi klien. Ini dapat ditempatkan di komponen induk mana pun, termasuk layout. Namun, menempatkannya di layout direkomendasikan karena Next.js berbagi kode layout di seluruh halaman, sehingga menjadi lebih efisien. Dengan menggunakan IntlayerClientProvider di layout, Anda menghindari inisialisasi ulang untuk setiap halaman, meningkatkan performa dan menjaga konteks lokalisasi yang konsisten di seluruh aplikasi Anda.

      • IntlayerServerProvider digunakan untuk menyediakan locale ke anak server. Ini tidak dapat disetel di layout.

        Layout dan halaman tidak dapat berbagi konteks server yang sama karena sistem konteks server didasarkan pada penyimpanan data per permintaan (melalui mekanisme cache React), yang menyebabkan setiap "konteks" dibuat ulang untuk segmen aplikasi yang berbeda. Menempatkan provider di layout bersama akan merusak isolasi ini, mencegah propagasi nilai konteks server yang benar ke komponen server Anda.
        Layout dan halaman tidak dapat berbagi konteks server yang sama karena sistem konteks server didasarkan pada penyimpanan data per permintaan (melalui mekanisme cache React), yang menyebabkan setiap “konteks” dibuat ulang untuk segmen aplikasi yang berbeda. Menempatkan provider di layout bersama akan memecah isolasi ini, sehingga mencegah propagasi nilai konteks server yang benar ke komponen server Anda.
      src/components/ClientComponentExample.tsx
      "use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // Membuat deklarasi konten terkait

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      src/components/ServerComponentExample.tsx
      import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // Membuat deklarasi konten terkait

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      Jika Anda ingin menggunakan konten Anda dalam atribut string, seperti alt, title, href, aria-label, dll., Anda harus memanggil nilai dari fungsi tersebut, 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.

    8. Internasionalisasi metadata Anda

      Opsional

      Jika Anda ingin menginternasionalisasi metadata Anda, seperti judul halaman Anda, Anda dapat menggunakan fungsi generateMetadata yang disediakan oleh Next.js. Di dalamnya, Anda dapat mengambil konten dari fungsi getIntlayer untuk menerjemahkan metadata Anda.

      src/app/[locale]/metadata.content.ts
      import { type Dictionary, t } from "intlayer";
import { Metadata } from "next";

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una aplicación Next.js",
    }),
    description: t({
      en: "Generated by create next app",
      fr: "Généré par create next app",
      es: "Generado por create next app",
    }),
  },
} satisfies Dictionary<Metadata>;

export default metadataContent;
      src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx
      import { getIntlayer, getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";
import type { LocalParams } from "next-intlayer";

export const generateMetadata = ({
  params: { locale },
}: LocalParams): Metadata => {
  const metadata = getIntlayer("page-metadata", locale);

  /**
   * Menghasilkan objek yang berisi semua url untuk setiap locale.
   *
   * Contoh:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // Mengembalikan
   *  // {
   *  //   en: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");
  const localizedUrl =
    multilingualUrls[locale as keyof typeof multilingualUrls];

  return {
    ...metadata,
    alternates: {
      canonical: localizedUrl,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: localizedUrl,
    },
  };
};

// ... Sisa kode
      Perhatikan bahwa fungsi getIntlayer yang diimpor dari next-intlayer mengembalikan konten Anda yang dibungkus dalam sebuah IntlayerNode, memungkinkan integrasi dengan editor visual. Sebaliknya, fungsi getIntlayer yang diimpor dari intlayer mengembalikan konten Anda secara langsung tanpa properti tambahan.

      Sebagai alternatif, Anda dapat menggunakan fungsi getTranslation untuk mendeklarasikan metadata Anda. Namun, menggunakan file deklarasi konten direkomendasikan untuk mengotomatisasi terjemahan metadata Anda dan mengeksternalisasi konten pada suatu saat.

      src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx
      import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import type { Metadata } from "next";
import type { LocalParams } from "next-intlayer";

export const generateMetadata = ({
  params: { locale },
}: LocalParams): Metadata => {
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  return {
    title: t<string>({
      en: "My title",
      fr: "Mon titre",
      es: "Mi título",
    }),
    description: t({
      en: "My description",
      fr: "Ma description",
      es: "Mi descripción",
    }),
  };
};

// ... Sisa kode
      Pelajari lebih lanjut tentang optimasi metadata di dokumentasi resmi Next.js.

    9. Internasionalisasi sitemap.xml dan robots.txt Anda

      Opsional

      Untuk menginternasionalkan sitemap.xml dan robots.txt Anda, Anda dapat menggunakan fungsi getMultilingualUrls yang disediakan oleh Intlayer. Fungsi ini memungkinkan Anda untuk menghasilkan URL multibahasa untuk sitemap Anda.

      src/app/sitemap.ts
      import { getMultilingualUrls } from "intlayer";
import type { MetadataRoute } from "next";

const sitemap = (): MetadataRoute.Sitemap => [
  {
    url: "https://example.com",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com"),
        "x-default": "https://example.com",
      },
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/login"),
        "x-default": "https://example.com/login",
      },
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/register"),
        "x-default": "https://example.com/register",
      },
    },
  },
];

export default sitemap;
      src/app/robots.ts
      import type { MetadataRoute } from "next";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

// Mendefinisikan aturan robots.txt untuk mengizinkan akses ke root dan melarang akses ke halaman login dan register dalam semua bahasa
const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]),
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;

export default robots;
      Pelajari lebih lanjut tentang optimasi sitemap di dokumentasi resmi Next.js. Pelajari lebih lanjut tentang optimasi robots.txt di dokumentasi resmi Next.js.

    10. Ubah bahasa konten Anda

      Opsional

      Untuk mengubah bahasa konten Anda di Next.js, cara yang direkomendasikan adalah menggunakan komponen Link untuk mengarahkan pengguna ke halaman yang sesuai dengan lokal yang diinginkan. Komponen Link memungkinkan prefetching halaman, yang membantu menghindari pemuatan ulang halaman secara penuh.

      src/components/LocaleSwitcher.tsx
      "use client";

import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import { type FC } from "react";
import Link from "next/link";

const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales, setLocale } =
    useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            hrefLang={localeItem}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
            replace // Akan memastikan bahwa tombol "kembali" pada browser akan mengarahkan ke halaman sebelumnya
          >
            <span>
              {/* Locale - misalnya 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>
        ))}
      </div>
    </div>
  );
};
      Cara alternatif adalah menggunakan fungsi setLocale yang disediakan oleh hook useLocale. Fungsi ini tidak akan memungkinkan prefetching halaman. Lihat dokumentasi useLocale hook untuk detail lebih lanjut.
      Anda juga dapat mengatur fungsi pada opsi onLocaleChange untuk memicu fungsi kustom saat locale berubah.
      src/components/LocaleSwitcher.tsx
      "use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Sisa kodeconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>    Ganti ke Bahasa Perancis  </button>);

      Referensi dokumentasi:

    11. Membuat Komponen Link yang Dilokalisasi

      Opsional

      Untuk memastikan navigasi aplikasi Anda menghormati locale saat ini, Anda dapat membuat komponen Link kustom. Komponen ini secara otomatis menambahkan prefix bahasa saat ini pada URL internal, sehingga misalnya, ketika pengguna berbahasa Prancis mengklik tautan ke halaman "About", mereka diarahkan ke /fr/about bukan /about.

      Perilaku ini berguna untuk beberapa alasan:

      • SEO dan Pengalaman Pengguna: URL yang dilokalkan membantu mesin pencari mengindeks halaman spesifik bahasa dengan benar dan menyediakan konten kepada pengguna dalam bahasa pilihan mereka.
      • Konsistensi: Dengan menggunakan tautan yang dilokalkan di seluruh aplikasi Anda, Anda menjamin bahwa navigasi tetap dalam locale saat ini, mencegah perubahan bahasa yang tidak diinginkan.
      • Pemeliharaan: Memusatkan logika lokalisasi dalam satu komponen menyederhanakan pengelolaan URL, membuat codebase Anda lebih mudah dipelihara dan dikembangkan seiring pertumbuhan aplikasi Anda.

      Berikut adalah implementasi komponen Link yang dilokalkan dalam TypeScript:

      src/components/Link.tsx
      "use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";

/**
 * Fungsi utilitas untuk memeriksa apakah URL yang diberikan adalah eksternal.
 * Jika URL dimulai dengan http:// atau https://, maka dianggap eksternal.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * Komponen Link kustom yang menyesuaikan atribut href berdasarkan locale saat ini.
 * Untuk tautan internal, menggunakan `getLocalizedUrl` untuk menambahkan prefix locale pada URL (misalnya, /fr/about).
 * Ini memastikan navigasi tetap dalam konteks locale yang sama.
 */
export const Link = forwardRef<
  HTMLAnchorElement,
  PropsWithChildren<NextLinkProps>
>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // Jika tautan bersifat internal dan href yang valid diberikan, dapatkan URL yang sudah dilokalkan.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} ref={ref} {...props}>
      {children}
    </NextLink>
  );
});

Link.displayName = "Link";

      Cara Kerjanya

      • Mendeteksi Tautan Eksternal:
        Fungsi pembantu checkIsExternalLink menentukan apakah sebuah URL bersifat eksternal. Tautan eksternal dibiarkan tidak berubah karena tidak memerlukan lokalisasi.

      • Mengambil Locale Saat Ini:

      • Melokalisasi URL:
        Untuk tautan internal (yaitu, bukan tautan eksternal), getLocalizedUrl digunakan untuk secara otomatis menambahkan prefiks URL dengan locale saat ini. Ini berarti jika pengguna Anda menggunakan bahasa Prancis, melewatkan /about sebagai href akan mengubahnya menjadi /fr/about.

      • Mengembalikan Link:
        Komponen mengembalikan elemen <a> dengan URL yang sudah dilokalisasi, memastikan navigasi konsisten dengan locale.

      Dengan mengintegrasikan komponen Link ini di seluruh aplikasi Anda, Anda mempertahankan pengalaman pengguna yang koheren dan sadar bahasa sekaligus mendapatkan manfaat dari peningkatan SEO dan kegunaan.

    12. Mendapatkan locale saat ini dalam Server Actions

      Opsional

      Jika Anda membutuhkan locale aktif di dalam Server Action (misalnya, untuk melokalkan email atau menjalankan logika yang sadar locale), panggil getLocale dari next-intlayer/server:

      src/app/actions/getLocale.ts
      "use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Lakukan sesuatu dengan locale};

      Fungsi getLocale mengikuti strategi bertingkat untuk menentukan locale pengguna:

      1. Pertama, memeriksa header permintaan untuk nilai locale yang mungkin telah diatur oleh middleware
      2. Jika tidak ditemukan locale di header, mencari locale yang disimpan di cookie
      3. Jika tidak ditemukan cookie, mencoba mendeteksi bahasa yang dipilih pengguna dari pengaturan browser mereka
      4. Sebagai upaya terakhir, ia akan kembali ke locale default yang dikonfigurasi dalam aplikasi

      Ini memastikan locale yang paling sesuai dipilih berdasarkan konteks yang tersedia.

    13. Optimalkan ukuran bundle Anda

      Opsional

      Saat menggunakan next-intlayer, kamus disertakan dalam bundle untuk setiap halaman secara default. Untuk mengoptimalkan ukuran bundle, Intlayer menyediakan plugin SWC opsional yang secara cerdas menggantikan panggilan useIntlayer menggunakan makro. Ini memastikan kamus hanya disertakan dalam bundle untuk halaman yang benar-benar menggunakannya.

      Untuk mengaktifkan optimasi ini, instal paket @intlayer/swc. Setelah terinstal, next-intlayer akan secara otomatis mendeteksi dan menggunakan plugin tersebut:

      bash
      npm install @intlayer/swc --save-dev
      Catatan: Optimasi ini hanya tersedia untuk Next.js 13 ke atas.
      Catatan: Paket ini tidak diinstal secara default karena plugin SWC masih bersifat eksperimental di Next.js. Hal ini mungkin berubah di masa depan.

      Catatan: Jika Anda mengatur opsi sebagai importMode: 'dynamic' atau importMode: 'fetch', maka akan bergantung pada Suspense, sehingga Anda harus membungkus pemanggilan useIntlayer Anda dalam batas Suspense. Itu berarti, Anda tidak dapat menggunakan useIntlayer secara langsung di tingkat atas komponen Halaman / Layout Anda.

    Konfigurasi TypeScript

    Intlayer menggunakan augmentasi modul untuk mendapatkan manfaat dari TypeScript dan membuat codebase Anda lebih kuat.

    Autocompletion

    Kesalahan Terjemahan

    Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan secara otomatis.

    tsconfig.json
    {  // ... Konfigurasi TypeScript Anda yang sudah ada  "include": [    // ... Konfigurasi TypeScript 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 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 Ekstensi VS Code Intlayer resmi.

    Pasang dari VS Code Marketplace

    Ekstensi ini menyediakan:

    • Autocompletion untuk kunci terjemahan.
    • Deteksi kesalahan waktu nyata untuk terjemahan yang hilang.
    • Pratinjau inline dari konten terjemahan.
    • 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.

    Next.js
    Next.js 15