Terjemahkan situs Next.js 16 Anda (tanpa [locale] di jalur halaman) menggunakan Intlayer | Internasionalisasi (i18n)

Lihat Templat Aplikasi di GitHub.

Daftar Isi

Apa itu Intlayer?

Intlayer adalah library internasionalisasi (i18n) yang inovatif dan open-source, dirancang untuk menyederhanakan dukungan multi-bahasa dalam aplikasi web modern. Intlayer terintegrasi dengan mulus ke framework Next.js 16 terbaru, termasuk App Router yang kuat. Library ini dioptimalkan untuk bekerja dengan Server Components agar rendering lebih efisien dan sepenuhnya kompatibel dengan Turbopack.

Dengan Intlayer, Anda dapat:

• Mengelola terjemahan dengan mudah menggunakan kamus deklaratif di tingkat komponen.
• Melokalkan metadata, rute, dan konten secara dinamis.
• Mengakses terjemahan di komponen client-side dan server-side.
• Menjamin dukungan TypeScript dengan tipe yang dihasilkan otomatis, meningkatkan autocompletion dan deteksi error.
• Manfaatkan fitur canggih, seperti deteksi locale dinamis dan pergantian bahasa.

Intlayer kompatibel dengan Next.js 12, 13, 14, dan 16. Jika Anda menggunakan Next.js Page Router, Anda dapat merujuk ke panduan ini. Untuk Next.js 12, 13, 14 dengan App Router, lihat panduan ini.

Panduan Langkah demi Langkah untuk Mengatur Intlayer di Aplikasi Next.js

Langkah 1: Instal Dependensi

Pasang paket yang diperlukan menggunakan npm:

npm install intlayer next-intlayernpx intlayer init

• intlayer

  Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpilasi, 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 menyertakan plugin Next.js untuk mengintegrasikan Intlayer dengan Webpack atau Turbopack, serta proxy untuk mendeteksi locale pilihan pengguna, mengelola cookie, dan menangani pengalihan URL.

Langkah 2: Konfigurasikan Proyek Anda

Berikut adalah struktur akhir yang akan kita buat:

.├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

Jika Anda tidak ingin routing locale, intlayer dapat digunakan sebagai provider / hook sederhana. Lihat panduan ini untuk detail lebih lanjut.

Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Lokal lainnya    ],    defaultLocale: Locales.ENGLISH,  },  routing: {    mode: "search-params", // atau `no-prefix` - Berguna untuk deteksi middleware  },};export default config;

Melalui berkas konfigurasi ini, Anda dapat mengatur URL terlokalisasi, pengalihan proxy, 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 ke Konfigurasi Next.js Anda

Konfigurasikan setup Next.js Anda untuk menggunakan Intlayer:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* opsi konfigurasi di sini */};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-file tersebut dalam mode pengembangan. Plugin ini mendefinisikan variabel lingkungan Intlayer dalam lingkungan Webpack atau Turbopack. Selain itu, plugin ini menyediakan alias untuk mengoptimalkan performa dan memastikan kompatibilitas dengan server components.

Fungsi withIntlayer() adalah fungsi yang mengembalikan Promise. Fungsi ini memungkinkan mempersiapkan kamus intlayer sebelum proses build dimulai. Jika Anda ingin menggunakannya bersama plugin lain, Anda dapat melakukan await padanya. Contoh:

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

Jika Anda ingin menggunakannya secara sinkron, Anda dapat menggunakan fungsi withIntlayerSync(). Contoh:

const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Intlayer secara otomatis mendeteksi apakah proyek Anda menggunakan webpack atau Turbopack berdasarkan flag baris perintah --webpack, --turbo, atau --turbopack, serta versi Next.js Anda saat ini.

Sejak next>=16, jika Anda menggunakan Rspack, Anda harus secara eksplisit memaksa Intlayer untuk menggunakan konfigurasi webpack dengan menonaktifkan Turbopack:

withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

Langkah 4: Definisikan Rute Locale Dinamis

Hapus semua isi RootLayout dan ganti dengan kode berikut:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Langkah 5: Deklarasikan Konten Anda

Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

import { t, type Dictionary } from "intlayer";import { Metadata } from "next";const metadataContent = {  key: "metadata",  content: {    title: t({      id: "Judul Proyek Saya",      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      id: "Temukan platform inovatif kami yang dirancang untuk menyederhanakan alur kerja Anda dan meningkatkan produktivitas.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      id: ["inovasi", "produktivitas", "alur kerja", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      id: ["inovasi", "produktivitas", "alur kerja", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },} as Dictionary<Metadata>;export default metadataContent;

import { t, type Dictionary } from "intlayer";/** @type {import('intlayer').Dictionary<import('next').Metadata>} */const metadataContent = {  key: "metadata",  content: {    title: t({      id: "Judul Proyek Saya",      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      id: "Temukan platform inovatif kami yang dirancang untuk menyederhanakan alur kerja Anda dan meningkatkan produktivitas.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      id: ["inovasi", "produktivitas", "alur kerja", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },};export default metadataContent;

import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    getStarted: {      main: t({        id: "Mulai dengan mengedit",        en: "Get started by editing",        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 sepanjang file tersebut dimasukkan ke dalam direktori contentDir (secara default, ./src). Dan sesuai dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

Langkah 6: Manfaatkan Konten dalam Kode Anda

Akses kamus konten Anda di seluruh aplikasi:

import type { FC } from "react";import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";import {  IntlayerServerProvider,  useIntlayer,  getLocale,} from "next-intlayer/server";import { NextPage } from "next";import { headers, cookies } from "next/headers";const PageContent: FC = () => {  const content = useIntlayer("page");  return (    <>      <p>{content.getStarted.main}</p>      <code>{content.getStarted.pageLink}</code>    </>  );};const Page: NextPage = async () => {  const locale = await getLocale();  return (    <IntlayerServerProvider locale={locale}>      <PageContent />      <ServerComponentExample />      <ClientComponentExample />    </IntlayerServerProvider>  );};export default Page;

• IntlayerClientProvider digunakan untuk menyediakan locale ke komponen sisi-klien. Dapat diletakkan di parent component mana pun, termasuk layout. Namun, menempatkannya di layout direkomendasikan karena Next.js membagikan kode layout di seluruh halaman, sehingga lebih efisien. Dengan menggunakan IntlayerClientProvider di layout, Anda menghindari menginisialisasi ulang untuk setiap halaman, meningkatkan performa dan menjaga konteks lokalisasi tetap konsisten di seluruh aplikasi Anda.

• IntlayerServerProvider digunakan untuk menyediakan locale kepada komponen anak di server. Tidak dapat ditempatkan di layout.

  Layout dan halaman tidak dapat berbagi server context yang sama karena sistem server context didasarkan pada penyimpanan data per-request (melalui mekanisme React's cache), yang menyebabkan setiap "context" dibuat ulang untuk segmen aplikasi yang berbeda. Menempatkan provider di layout bersama akan merusak isolasi ini, sehingga mencegah propagasi nilai server context yang benar ke komponen server Anda.

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Buat deklarasi konten terkait  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

import type { FC } from "react";import { useIntlayer } from "next-intlayer/server";export const ServerComponentExample: FC = () => {  const content = useIntlayer("server-component-example"); // Buat deklarasi konten terkait  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

Jika Anda ingin menggunakan konten Anda dalam atribut bertipe string, seperti alt, title, href, aria-label, dll., Anda harus memanggil nilai fungsi tersebut, seperti:

<img src={content.image.src.value} alt={content.image.value} />

Untuk mempelajari lebih lanjut tentang hook useIntlayer, lihat dokumentasi.

(Opsional) Langkah 7: Konfigurasikan Proxy untuk Deteksi Locale

Atur proxy untuk mendeteksi locale preferensi pengguna:

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

intlayerProxy digunakan untuk mendeteksi locale pilihan pengguna dan mengarahkan mereka ke URL yang sesuai seperti ditentukan dalam konfigurasi. Selain itu, ini memungkinkan penyimpanan locale pilihan pengguna dalam cookie.

Jika Anda perlu menggabungkan beberapa proxy bersama-sama (misalnya, intlayerProxy dengan otentikasi atau proxy kustom), Intlayer kini menyediakan helper yang disebut multipleProxies.

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

(Opsional) Langkah 8: Ubah bahasa konten Anda

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

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale({    onChange: () => window.location.reload(),  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Kode locale - mis. FR */}              {localeItem}            </span>            <span>              {/* Nama bahasa dalam locale-nya sendiri - mis. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Nama bahasa dalam locale saat ini - mis. Francés ketika locale saat ini diset ke Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Nama bahasa dalam Bahasa Inggris - mis. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Cara alternatif adalah menggunakan fungsi setLocale yang disediakan oleh hook useLocale. Fungsi ini tidak akan memungkinkan prefetching halaman. Lihat dokumentasi hook useLocale untuk detail lebih lanjut.

Referensi dokumentasi:

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

(Opsional) Langkah 9: Dapatkan locale saat ini di Server Actions

Jika Anda membutuhkan locale aktif di dalam Server Action (mis. untuk melokalisasi email atau menjalankan logika yang peka terhadap locale), panggil getLocale dari next-intlayer/server:

"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, ia memeriksa header permintaan untuk nilai locale yang mungkin telah disetel oleh proxy
2. Jika tidak ada locale yang ditemukan di header, ia mencari locale yang disimpan dalam cookie
3. Jika tidak ada cookie yang ditemukan, ia mencoba mendeteksi bahasa pilihan pengguna dari pengaturan browser mereka
4. Sebagai upaya terakhir, ia kembali ke locale default yang dikonfigurasi aplikasi

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

(Opsional) Langkah 10: Optmize 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 pemanggilan useIntlayer menggunakan makro. Ini memastikan kamus hanya disertakan dalam bundle untuk halaman yang benar-benar menggunakannya.

Untuk mengaktifkan optimisasi ini, pasang paket @intlayer/swc. Setelah terpasang, next-intlayer akan secara otomatis mendeteksi dan menggunakan plugin tersebut:

npm install @intlayer/swc --save-devnpx intlayer init

Catatan: Optimisasi ini hanya tersedia untuk Next.js 13 ke atas.

Catatan: Paket ini tidak terpasang secara default karena plugin SWC masih eksperimental pada Next.js. Hal ini dapat berubah di masa depan.

Catatan: Jika Anda mengatur opsi sebagai importMode: 'dynamic' atau importMode: 'live', itu akan bergantung pada Suspense, jadi Anda harus membungkus pemanggilan useIntlayer Anda dalam boundary Suspense. Artinya, Anda tidak akan dapat menggunakan useIntlayer langsung di tingkat atas komponen Page / Layout Anda.

Pantau perubahan kamus pada Turbopack

Ketika menggunakan Turbopack sebagai server pengembangan dengan perintah next dev, perubahan kamus tidak akan terdeteksi secara otomatis secara default.

Keterbatasan ini terjadi karena Turbopack tidak dapat menjalankan plugin webpack secara paralel untuk memantau perubahan pada file konten Anda. Untuk mengatasi hal ini, Anda perlu menggunakan perintah intlayer watch untuk menjalankan server pengembangan dan watcher build Intlayer secara bersamaan.

{  // ... Konfigurasi package.json Anda yang sudah ada  "scripts": {    // ... Konfigurasi skrip yang sudah ada    "dev": "intlayer watch --with 'next dev'",  },}

Jika Anda menggunakan next-intlayer@<=6.x.x, Anda perlu mempertahankan flag --turbopack agar aplikasi Next.js 16 bekerja dengan benar menggunakan Turbopack. Kami merekomendasikan menggunakan next-intlayer@>=7.x.x untuk menghindari keterbatasan ini.

Konfigurasi TypeScript

Intlayer menggunakan module augmentation untuk mendapatkan manfaat 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 secara otomatis  ],}

Konfigurasi Git

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

Untuk melakukan ini, Anda bisa menambahkan instruksi berikut ke file .gitignore Anda:

# Abaikan berkas yang dihasilkan oleh Intlayer.intlayer

Ekstensi VS Code

Untuk meningkatkan pengalaman pengembangan Anda dengan Intlayer, Anda dapat memasang resmi Ekstensi Intlayer untuk VS Code.

Instal 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, lihat dokumentasi Intlayer VS Code Extension.

Lebih Lanjut

Untuk langkah lebih lanjut, Anda dapat mengimplementasikan editor visual atau mengeksternalisasi konten Anda menggunakan CMS.