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

Lihat Templat Aplikasi di GitHub.

Daftar Isi

Mengapa Intlayer dibandingkan alternatif?

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

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

1. 1

   Instal Dependensi

   Pasang paket yang diperlukan menggunakan npm:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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.

2. 2

   Konfigurasikan Proyek Anda

   Berikut adalah struktur akhir yang akan kita buat:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   .├── 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:

   intlayer.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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.

3. 3

   Integrasikan Intlayer ke Konfigurasi Next.js Anda

   Konfigurasikan setup Next.js Anda untuk menggunakan Intlayer:

   next.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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:

   ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

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

   ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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:

   ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

4. 4

   Definisikan Rute Locale Dinamis

   Hapus semua isi RootLayout dan ganti dengan kode berikut:

   src/app/layout.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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 (): Promise<Metadata> => {
     const locale = await getLocale();
     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;

5. 5

   Deklarasikan Konten Anda

   Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

   src/app/metadata.content.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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;

   src/app/page.content.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

6. 6

   Manfaatkan Konten dalam Kode Anda

   Akses kamus konten Anda di seluruh aplikasi:

   src/app/page.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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.

   src/components/clientComponentExample/ClientComponentExample.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   src/components/serverComponentExample/ServerComponentExample.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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:

   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.

7. 7

   Konfigurasikan Proxy untuk Deteksi Locale

   Opsional

   Atur proxy untuk mendeteksi locale preferensi pengguna:

   src/proxy.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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.

   ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

8. 8

   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. Komponen Link memungkinkan prefetching halaman, yang membantu menghindari reload halaman penuh.

   src/components/localeSwitcher/LocaleSwitcher.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

9. 9

   Dapatkan locale saat ini di Server Actions

   Opsional

   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:

   src/app/actions/getLocale.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

10. 10

    Optimize 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 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:

    bash

    Salin konten

    Salin kode

    Salin kode ke clipboard

    npm install @intlayer/swc --save-dev

    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: 'fetch', 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.