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

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

Dalam artikel ini, kami akan membahas cara menambahkan internasionalisasi ke aplikasi React Next.js Anda, dengan rendering sisi server. 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: Instal pustaka i18n

Untuk menerapkan 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 melelahkan.

Mari kita instal menggunakan npm di terminal Anda:

npm install tacotranslate

Langkah 2: Buat akun TacoTranslate gratis

Sekarang setelah Anda memasang modul ini, saatnya membuat akun TacoTranslate Anda, sebuah proyek terjemahan, dan kunci API terkait. Buat akun di sini. Gratis, dan tidak perlu menambahkan kartu kredit.

Di dalam antarmuka aplikasi TacoTranslate, buat sebuah proyek, lalu buka tab kunci API. Buat satu kunci read dan satu kunci read/write. Kita akan menyimpannya sebagai variabel lingkungan. Kunci read adalah apa yang kami sebut public dan kunci read/write adalah secret. Misalnya, Anda bisa menambahkannya ke file .env di root proyek Anda.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

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

• TACOTRANSLATE_DEFAULT_LOCALE: Kode locale default sebagai fallback. 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 selengkapnya tentang origins di sini.

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

Step 3: Menyiapkan TacoTranslate

Untuk mengintegrasikan TacoTranslate dengan aplikasi Anda, Anda perlu membuat sebuah klien menggunakan kunci API yang disebutkan sebelumnya. Misalnya, buat sebuah 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 dalam waktu singkat.

Membuat klien di file terpisah membuatnya mudah digunakan lagi nanti. getLocales hanyalah fungsi utilitas dengan beberapa penanganan kesalahan bawaan. Sekarang, buat file bernama /app/[locale]/tacotranslate.tsx, di mana kita akan mengimplementasikan penyedia 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.

Setelah penyedia konteks siap digunakan, buat sebuah berkas bernama /app/[locale]/layout.tsx, yang menjadi tata letak utama dalam aplikasi kami. 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 kami menggunakan parameter Dynamic Route [locale] untuk mengambil terjemahan untuk bahasa tersebut. Selain itu, generateStaticParams memastikan semua kode locale yang telah Anda aktifkan untuk proyek Anda dirender sebelumnya.

Sekarang, mari kita buat halaman pertama kita! Buat sebuah file bernama /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 memberi tahu Next.js untuk membangun ulang halaman setelah 60 detik, dan menjaga terjemahan Anda tetap mutakhir.

Langkah 4: Mengimplementasikan rendering di sisi server

TacoTranslate mendukung rendering di sisi server. Hal ini secara signifikan meningkatkan pengalaman pengguna dengan menampilkan konten yang sudah diterjemahkan secara langsung, alih-alih menampilkan kilasan konten yang belum diterjemahkan terlebih dahulu. Selain itu, kita dapat melewati permintaan jaringan di sisi klien, karena kita sudah memiliki terjemahan yang dibutuhkan untuk halaman yang sedang dilihat pengguna.

Untuk menyiapkan rendering sisi server, buat atau ubah /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};
};

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

Untuk memastikan routing dan pengalihan berfungsi seperti yang diharapkan, kita perlu membuat file bernama /middleware.ts. Dengan menggunakan Middleware, kita dapat mengarahkan pengguna ke halaman yang ditampilkan 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 mengubah bahasa pilihan pengguna. Silakan lihat kode contoh lengkap untuk ide tentang cara melakukannya!

Langkah 5: Terapkan dan uji!

Selesai! Aplikasi React Anda sekarang akan diterjemahkan secara otomatis ketika Anda menambahkan string apa pun ke komponen Translate. Perlu dicatat bahwa hanya lingkungan dengan izin read/write pada kunci API yang dapat membuat string baru untuk diterjemahkan. Kami menyarankan memiliki lingkungan staging tertutup dan aman tempat Anda dapat menguji aplikasi produksi Anda dengan kunci API semacam itu, menambahkan string baru sebelum diluncurkan. Ini akan mencegah siapa pun mencuri kunci API rahasia Anda, serta berpotensi mencegah proyek terjemahan Anda membengkak akibat penambahan string baru yang tidak terkait.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!