Cara mengimplementasikan internasionalisasi dalam aplikasi Next.js yang menggunakan App Router

Seiring dunia menjadi semakin terglobalisasi, semakin penting bagi pengembang web untuk membangun aplikasi yang dapat melayani pengguna dari berbagai negara dan budaya. Salah satu cara utama untuk mencapai ini adalah melalui internasionalisasi (i18n), yang memungkinkan Anda menyesuaikan aplikasi Anda ke berbagai bahasa, mata uang, dan format tanggal.

Dalam artikel ini, kita akan mengeksplorasi cara menambahkan internasionalisasi ke aplikasi React Next.js Anda, dengan server side rendering. TL;DR: Lihat contoh lengkapnya di sini.

Panduan ini untuk aplikasi Next.js yang menggunakan App Router.
Jika Anda menggunakan Pages Router, lihat panduan ini sebagai gantinya.

Langkah 1: Pasang pustaka i18n

Untuk mengimplementasikan internasionalisasi di aplikasi Next.js Anda, pertama-tama kita akan memilih sebuah pustaka i18n. Ada beberapa pustaka populer, termasuk next-intl. Namun, dalam contoh ini, kita akan menggunakan TacoTranslate.

TacoTranslate secara otomatis menerjemahkan string Anda ke bahasa apa pun menggunakan AI mutakhir, dan membebaskan Anda dari pengelolaan file JSON yang membosankan.

Mari instal menggunakan npm di terminal Anda:

npm install tacotranslate

Langkah 2: Buat akun TacoTranslate gratis

Sekarang setelah Anda menginstal modulnya, saatnya membuat akun TacoTranslate Anda, sebuah proyek terjemahan, dan API key yang terkait. Buat akun di sini. Ini gratis, dan tidak mengharuskan Anda menambahkan kartu kredit.

Dalam antarmuka aplikasi TacoTranslate, buat sebuah proyek, dan navigasikan ke tab API keys-nya. Buat satu kunci read dan satu kunci read/write. Kami akan menyimpannya sebagai variabel lingkungan. Kunci read adalah apa yang kami sebut sebagai public dan kunci read/write adalah secret. Sebagai contoh, Anda dapat menambahkannya ke file .env di root proyek Anda.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Pastikan untuk tidak pernah membocorkan kunci API rahasia read/write ke lingkungan produksi sisi klien.

Kami juga akan menambahkan dua variabel lingkungan lagi: TACOTRANSLATE_DEFAULT_LOCALE dan TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Kode lokal fallback default. Dalam contoh ini, kita akan mengaturnya ke en untuk Bahasa Inggris.
• TACOTRANSLATE_ORIGIN: “Folder” tempat string Anda akan disimpan, seperti URL situs web Anda. Baca lebih lanjut tentang origin di sini.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Langkah 3: Menyiapkan TacoTranslate

Untuk mengintegrasikan TacoTranslate dengan aplikasi Anda, Anda perlu membuat klien menggunakan kunci API yang telah dibuat sebelumnya. Sebagai contoh, buat file bernama /tacotranslate-client.js.

const {default: createTacoTranslateClient} = require('tacotranslate');

const tacoTranslate = createTacoTranslateClient({
	apiKey:
		process.env.TACOTRANSLATE_SECRET_API_KEY ??
		process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
		process.env.TACOTRANSLATE_API_KEY,
	projectLocale:
		process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Kami akan secara otomatis mendefinisikan TACOTRANSLATE_API_KEY dan TACOTRANSLATE_PROJECT_LOCALE sebentar lagi.

Membuat client dalam file terpisah membuatnya mudah digunakan kembali nanti. getLocales hanyalah fungsi utilitas dengan beberapa penanganan error bawaan. Sekarang, buat file bernama /app/[locale]/tacotranslate.tsx, di mana kita akan mengimplementasikan provider TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Perhatikan 'use client'; yang menunjukkan bahwa ini adalah komponen klien.

Dengan penyedia konteks yang kini siap digunakan, buatlah sebuah file bernama /app/[locale]/layout.tsx, yaitu tata letak root dalam aplikasi kita. Perhatikan bahwa jalur ini memiliki folder yang menggunakan Dynamic Routes, di mana [locale] adalah parameter dinamis.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Hal pertama yang perlu dicatat di sini adalah bahwa kita menggunakan parameter Dynamic Route kami [locale] untuk mengambil terjemahan untuk bahasa tersebut. Selain itu, generateStaticParams memastikan semua kode lokal yang telah Anda aktifkan untuk proyek Anda sudah dilakukan pre-render.

Sekarang, mari kita buat halaman pertama kita! Buat file dengan nama /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Perhatikan variabel revalidate yang memberitahu Next.js untuk membangun ulang halaman setelah 60 detik, dan menjaga terjemahan Anda tetap terbaru.

Langkah 4: Menerapkan server side rendering

TacoTranslate mendukung server side rendering. Ini secara signifikan meningkatkan pengalaman pengguna dengan menampilkan konten yang sudah diterjemahkan secara langsung, daripada terlebih dahulu menampilkan konten yang belum diterjemahkan dalam waktu singkat. Selain itu, kita dapat melewati permintaan jaringan di sisi klien, karena kita sudah memiliki terjemahan yang dibutuhkan untuk halaman yang sedang dilihat pengguna.

Untuk mengatur server side rendering, buat atau modifikasi /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			client: tacoTranslateClient,
			isProduction:
				process.env.TACOTRANSLATE_ENV === 'production' ||
				process.env.VERCEL_ENV === 'production' ||
				(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
					process.env.NODE_ENV === 'production'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Modifikasi pengecekan isProduction agar sesuai dengan pengaturan Anda. Jika true, TacoTranslate akan menampilkan API key publik. Jika kita berada di lingkungan lokal, pengujian, atau staging (isProduction is false), kita akan menggunakan API key rahasia read/write untuk memastikan string baru dikirim untuk diterjemahkan.

Untuk memastikan routing dan pengalihan bekerja sesuai harapan, kita perlu membuat file bernama /middleware.ts. Dengan menggunakan Middleware, kita dapat mengarahkan pengguna ke halaman yang disajikan dalam bahasa pilihan mereka.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Pastikan untuk mengatur matcher sesuai dengan dokumentasi Next.js Middleware.

Di sisi klien, Anda dapat mengubah cookie locale untuk mengganti bahasa preferensi pengguna. Silakan lihat kode contoh lengkap untuk ide tentang cara melakukannya!

Langkah 5: Deploy dan uji!

Kita sudah selesai! Aplikasi React Anda sekarang akan diterjemahkan secara otomatis ketika Anda menambahkan string apa pun ke komponen Translate. Perlu diingat bahwa hanya lingkungan dengan izin read/write pada API key yang dapat membuat string baru untuk diterjemahkan. Kami menyarankan untuk memiliki lingkungan staging yang tertutup dan aman di mana Anda dapat menguji aplikasi produksi Anda menggunakan API key seperti itu, menambahkan string baru sebelum diluncurkan secara live. Ini akan mencegah siapa pun mencuri API key rahasia Anda, dan berpotensi membengkakkan proyek terjemahan Anda dengan menambahkan string baru yang tidak terkait.

Pastikan untuk melihat contoh lengkapnya di profil GitHub kami. Di sana, Anda juga akan menemukan contoh bagaimana melakukannya menggunakan Pages Router! Jika Anda mengalami masalah, jangan ragu untuk menghubungi kami, dan kami akan dengan senang hati membantu.

TacoTranslate memungkinkan Anda untuk secara otomatis melokalkan aplikasi React Anda dengan cepat ke dan dari bahasa apa pun. Mulai sekarang juga!