Terjemahkan situs web Next.js dan Page Router Anda menggunakan Intlayer | Internasionalisasi (i18n)

Daftar Isi

Apa itu Intlayer?

Intlayer adalah perpustakaan internasionalisasi (i18n) sumber terbuka yang inovatif, dirancang untuk mempermudah dukungan multibahasa dalam aplikasi web modern. Intlayer terintegrasi dengan mulus dengan kerangka kerja Next.js terbaru, termasuk Page Router tradisionalnya.

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.
• Memanfaatkan fitur canggih, seperti deteksi dan pengalihan locale secara dinamis.

Intlayer kompatibel dengan Next.js 12, 13, 14, dan 15. Jika Anda menggunakan Next.js App Router, lihat panduan App Router. Untuk Next.js 15, ikuti panduan ini.

Panduan Langkah demi Langkah untuk Mengatur Intlayer dalam Aplikasi Next.js Menggunakan Page Router

Langkah 1: Instalasi Dependensi

Instal paket yang diperlukan menggunakan manajer paket pilihan Anda:

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 provider dan hook 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.

Langkah 2: Konfigurasikan Proyek Anda

Buat file konfigurasi untuk mendefinisikan bahasa yang didukung oleh aplikasi Anda:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Tambahkan locale lain Anda di sini
    ],
    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.

Langkah 3: Integrasikan Intlayer dengan Konfigurasi Next.js

Ubah konfigurasi Next.js Anda untuk menggabungkan Intlayer:

import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {  // Konfigurasi Next.js Anda yang sudah ada};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. Plugin ini juga 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

Salin konten

Salin kode

Salin kode ke clipboard

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

Langkah 4: Konfigurasikan Middleware untuk Deteksi Locale

Siapkan middleware untuk secara otomatis mendeteksi dan menangani locale yang dipilih pengguna:

export { intlayerProxy as middleware } from "next-intlayer/middleware";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};

Sesuaikan parameter matcher untuk mencocokkan rute aplikasi Anda. Untuk informasi lebih lanjut, lihat dokumentasi Next.js tentang konfigurasi matcher.

Langkah 5: Definisikan Rute Locale Dinamis

Implementasikan routing dinamis untuk menyajikan konten yang dilokalkan berdasarkan locale pengguna.

1. Buat Halaman Khusus Locale:

   Ganti nama file halaman utama Anda untuk menyertakan segmen dinamis [locale].

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   mv src/pages/index.tsx src/pages/[locale]/index.tsx

2. Perbarui _app.tsx untuk Menangani Lokalisasi:

   Modifikasi _app.tsx Anda untuk menyertakan penyedia Intlayer.

   src/pages/_app.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { FC } from "react";import type { AppProps } from "next/app";import { IntlayerClientProvider } from "next-intlayer";const App = FC<AppProps>({ Component, pageProps }) => {  const { locale } = pageProps;  return (    <IntlayerClientProvider locale={locale}>      <Component {...pageProps} />    </IntlayerClientProvider>  );}export default MyApp;

3. Atur getStaticPaths dan getStaticProps:

   plaintext

   Salin konten

   Salin kode

   Salin kode ke clipboard

   Di `[locale]/index.tsx` Anda, definisikan paths dan props untuk menangani berbagai locale.

getStaticPaths dan getStaticProps memastikan bahwa aplikasi Anda membangun terlebih dahulu halaman-halaman yang diperlukan untuk semua locale di Next.js Page Router. Pendekatan ini mengurangi komputasi saat runtime dan menghasilkan pengalaman pengguna yang lebih baik. Untuk detail lebih lanjut, lihat dokumentasi Next.js tentang getStaticPaths dan getStaticProps.

Langkah 6: Deklarasikan Konten Anda

Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan.

import { t, type Dictionary } from "intlayer";

const homeContent = {
  key: "home",
  content: {
    title: t({
      en: "Welcome to My Website",
      fr: "Bienvenue sur mon site Web",
      es: "Bienvenido a mi sitio web",
    }),
    description: t({
      en: "Mulailah dengan mengedit halaman ini.",
      fr: "Commencez par éditer cette page.",
      es: "Comience por editar esta página.",
    }),
  },
} satisfies Dictionary;

export default homeContent;

Untuk informasi lebih lanjut tentang deklarasi konten, lihat panduan deklarasi konten.

Langkah 7: Gunakan Konten dalam Kode Anda

Akses kamus konten Anda di seluruh aplikasi untuk menampilkan konten yang diterjemahkan.

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";
import { ComponentExample } from "@components/ComponentExample";

const HomePage: FC = () => {
  const content = useIntlayer("home");

  return (
    <div>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
      <ComponentExample />
      {/* Komponen tambahan */}
    </div>
  );
};

// ... Sisa kode, termasuk getStaticPaths dan getStaticProps

export default HomePage;

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

export const ComponentExample: FC = () => {
  const content = useIntlayer("component-example"); // Pastikan Anda memiliki deklarasi konten yang sesuai

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

Saat menggunakan terjemahan dalam atribut string (misalnya, alt, title, href, aria-label), panggil

nilai fungsi sebagai berikut:

html

Salin konten

Salin kode

Salin kode ke clipboard

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

(Opsional) Langkah 8: Internasionalisasi metadata Anda

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

import { type Dictionary, t } from "intlayer";
import { type 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;

import { GetStaticPaths, GetStaticProps } from "next";
import { getIntlayer, getMultilingualUrls } from "intlayer";
import { useIntlayer } from "next-intlayer";
import Head from "next/head";
import type { FC } from "react";

interface HomePageProps {
  locale: string;
  metadata: {
    title: string;
    description: string;
  };
  multilingualUrls: Record<string, string>;
}

const HomePage: FC<HomePageProps> = ({
  metadata,
  multilingualUrls,
  locale,
}) => {
  const content = useIntlayer("page");

  return (
    <div>
      <Head>
        <title>{metadata.title}</title>
        <meta name="description" content={metadata.description} />
        {/* Menghasilkan tag hreflang untuk SEO */}
        {Object.entries(multilingualUrls).map(([lang, url]) => (
          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
        ))}
        <link rel="canonical" href={multilingualUrls[locale]} />
      </Head>

      {/* Konten halaman */}
      <main>{/* Konten halaman Anda di sini */}</main>
    </div>
  );
};

export const getStaticProps: GetStaticProps<HomePageProps> = async ({
  params,
}) => {
  const locale = params?.locale as string;

  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("/");

  return {
    props: {
      locale,
      metadata,
      multilingualUrls,
    },
  };
};

export default HomePage;

// ... Sisa kode termasuk getStaticPaths

Perlu dicatat bahwa fungsi getIntlayer yang diimpor dari next-intlayer mengembalikan konten Anda yang dibungkus dalam IntlayerNode, memungkinkan integrasi dengan visual editor. 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 titik.

import { GetStaticPaths, GetStaticProps } from "next";
import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import { useIntlayer } from "next-intlayer";
import Head from "next/head";
import type { FC } from "react";

interface HomePageProps {
  locale: string;
  metadata: {
    title: string;
    description: string;
  };
  multilingualUrls: Record<string, string>;
}

const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => {
  const content = useIntlayer("page");

  return (
    <div>
      <Head>
        <title>{metadata.title}</title>
        <meta name="description" content={metadata.description} />
        {/* Menghasilkan tag hreflang untuk SEO */}
        {Object.entries(multilingualUrls).map(([lang, url]) => (
          <link
            key={lang}
            rel="alternate"
            hrefLang={lang}
            href={url}
          />
        ))}
        <link rel="canonical" href={multilingualUrls[locale]} />
      </Head>

      {/* Konten halaman */}
      <main>
        {/* Konten halaman Anda di sini */}
      </main>
    </div>
  );
};

export const getStaticProps: GetStaticProps<HomePageProps> = async ({
  params
}) => {
  const locale = params?.locale as string;
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  const metadata = {
    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",
    }),
  };

  const multilingualUrls = getMultilingualUrls("/");

  return {
    props: {
      locale,
      metadata,
      multilingualUrls,
    },
  };
};

export default HomePage;

// ... Sisa kode termasuk getStaticPaths

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

(Opsional) Langkah 9: Ubah bahasa konten Anda

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

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

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

  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)}
          >
            <span>
              {/* Locale - misal FR */}
              {localeItem}
            </span>
            <span>
              {/* Bahasa dalam Locale-nya sendiri - misal 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 dan akan memuat ulang halaman.

Dalam kasus ini, tanpa pengalihan menggunakan router.push, hanya kode sisi server Anda yang akan mengubah locale dari konten.

"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)}>    Ubah ke Bahasa Perancis  </button>);

API useLocalePageRouter sama dengan useLocale. Untuk mempelajari lebih lanjut tentang hook useLocale, lihat dokumentasi.

Referensi dokumentasi:

• hook getLocaleName
• hook getLocalizedUrl
• hook getHTMLTextDir
• atribut hrefLang
• atribut lang
• atribut dir
• atribut aria-current

(Opsional) Langkah 10: Membuat Komponen Link yang Dilokalkan

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 Perancis mengklik tautan ke halaman "About", mereka akan 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 terduga.
• 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:

"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 disediakan, dapatkan URL yang 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:
  Hook useLocale menyediakan locale saat ini (misalnya, fr untuk bahasa Perancis).

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

• Mengembalikan Link:
  Komponen mengembalikan elemen <a> dengan URL yang sudah dilokalkan, 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.

(Opsional) Langkah 11: Optimalkan ukuran bundle Anda

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:

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 akan berubah di masa depan.

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.

{  // ... Konfigurasi TypeScript Anda yang sudah ada  "include": [    // ... Konfigurasi TypeScript Anda yang sudah ada    ".intlayer/**/*.ts", // Sertakan tipe yang dihasilkan otomatis  ],}

Konfigurasi Git

Untuk menjaga kebersihan repositori Anda dan menghindari commit file yang dihasilkan, disarankan untuk mengabaikan file yang dibuat oleh Intlayer.

Tambahkan baris berikut ke file .gitignore Anda:

# 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.
• Aksi cepat untuk dengan mudah membuat dan memperbarui terjemahan.

Untuk informasi lebih lanjut tentang cara menggunakan ekstensi ini, lihat dokumentasi Ekstensi VS Code Intlayer.

Sumber Daya Tambahan

• Dokumentasi Intlayer: Repositori GitHub
• Panduan Kamus: Kamus
• Dokumentasi Konfigurasi: Panduan Konfigurasi

Dengan mengikuti panduan ini, Anda dapat mengintegrasikan Intlayer secara efektif ke dalam aplikasi Next.js Anda menggunakan Page Router, memungkinkan dukungan internasionalisasi yang kuat dan skalabel untuk proyek web Anda.

Melangkah Lebih Jauh

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