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

Apabila dunia menjadi semakin global, semakin penting bagi pembangun web untuk membina aplikasi yang dapat memenuhi keperluan pengguna dari negara dan budaya yang berbeza. Salah satu cara utama untuk mencapai ini ialah melalui pengantarabangsaan (i18n), yang membolehkan anda menyesuaikan aplikasi anda kepada bahasa, mata wang, dan format tarikh yang berbeza.

Dalam artikel ini, kami akan meneroka cara menambah pengantarabangsaan kepada aplikasi React Next.js anda, dengan perenderan di sisi pelayan. TL;DR: Lihat contoh penuh di sini.

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

Langkah 1: Pasang perpustakaan i18n

Untuk mengimplementasikan pengantarabangsaan dalam aplikasi Next.js anda, kita akan mula dengan memilih perpustakaan i18n. Terdapat beberapa perpustakaan popular, termasuk next-intl. Dalam contoh ini, walau bagaimanapun, kita akan menggunakan TacoTranslate.

TacoTranslate secara automatik menterjemahkan rentetan teks anda ke mana-mana bahasa menggunakan AI terkini, dan membebaskan anda daripada pengurusan fail JSON yang membosankan.

Mari pasang ia menggunakan npm dalam terminal anda:

npm install tacotranslate

Langkah 2: Buat akaun TacoTranslate percuma

Sekarang anda telah memasang modul ini, tiba masanya untuk mencipta akaun TacoTranslate anda, projek terjemahan, dan kekunci API yang berkaitan. Buat akaun di sini. Ia percuma, dan tidak memerlukan anda menambah kad kredit.

Di dalam antara muka aplikasi TacoTranslate, buat sebuah projek, dan pergi ke tab kekunci API. Buat satu kekunci read, dan satu lagi kekunci read/write. Kami akan menyimpannya sebagai pembolehubah persekitaran. Kekunci read adalah apa yang kami panggil public, dan kekunci read/write ialah secret. Sebagai contoh, anda boleh menambahkannya ke fail .env di akar projek anda.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Pastikan anda tidak pernah mendedahkan kunci API rahsia read/write kepada persekitaran produksi di sisi klien.

Kami juga akan menambah dua lagi pembolehubah persekitaran: TACOTRANSLATE_DEFAULT_LOCALE dan TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Kod lokal lalai (fallback). Dalam contoh ini, kami akan menetapkannya kepada en untuk Bahasa Inggeris.
• TACOTRANSLATE_ORIGIN: “Folder” di mana rentetan anda akan disimpan, seperti URL laman 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 sebuah klien menggunakan kekunci API yang dinyatakan sebelumnya. Contohnya, buat sebuah fail 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 automatik mendefinisikan TACOTRANSLATE_API_KEY dan TACOTRANSLATE_PROJECT_LOCALE tidak lama lagi.

Mencipta klien dalam fail berasingan memudahkan penggunaannya semula kemudian. getLocales hanyalah fungsi utiliti dengan beberapa pengendalian ralat terbina dalam. Sekarang, buat fail bernama /app/[locale]/tacotranslate.tsx, di mana kita akan melaksanakan 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 bahawa ini adalah komponen klien.

Dengan penyedia konteks kini sedia untuk digunakan, buat satu fail bernama /app/[locale]/layout.tsx, susun atur utama dalam aplikasi kami. Perhatikan bahawa laluan ini mempunyai folder yang menggunakan Dynamic Routes, di mana [locale] ialah parameter dinamik.

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

Perkara pertama yang perlu diperhatikan di sini ialah kami menggunakan parameter Dynamic Route [locale] untuk mendapatkan terjemahan bagi bahasa tersebut. Selain itu, generateStaticParams memastikan semua kod lokal yang telah anda aktifkan untuk projek anda diprapaparkan.

Sekarang, mari bina halaman pertama kita! Buat fail 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 pembolehubah revalidate yang memberitahu Next.js untuk membina semula halaman selepas 60 saat, dan memastikan terjemahan anda sentiasa dikemas kini.

Langkah 4: Melaksanakan rendering di sisi pelayan

TacoTranslate menyokong rendering sisi pelayan. Ini meningkatkan pengalaman pengguna dengan ketara kerana ia memaparkan kandungan yang telah diterjemahkan serta-merta, dan bukannya menunjukkan kilasan kandungan yang belum diterjemahkan terlebih dahulu. Selain itu, kita boleh mengelakkan permintaan rangkaian pada klien kerana kita sudah mempunyai terjemahan yang diperlukan untuk halaman yang sedang dilihat oleh pengguna.

Untuk menyediakan penjanaan di sisi pelayan, 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 mengikut tetapan anda. Jika true, TacoTranslate akan memaparkan kunci API awam. Jika kita berada dalam persekitaran tempatan, ujian, atau staging (isProduction is false), kita akan menggunakan kunci API rahsia read/write untuk memastikan rentetan baru dihantar untuk diterjemahkan.

Untuk memastikan penghalaan dan pengalihan berfungsi seperti yang diharapkan, kita perlu membuat fail bernama /middleware.ts. Dengan menggunakan Middleware, kita boleh mengalihkan pengguna ke halaman yang dipaparkan 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 menyediakan matcher selaras dengan dokumentasi Next.js Middleware.

Di pihak klien, anda boleh mengubah kuki locale untuk menukar bahasa pilihan pengguna. Sila lihat kod contoh lengkap untuk idea tentang cara melakukan ini!

Langkah 5: Lancarkan dan uji!

Selesai! Aplikasi React anda kini akan diterjemahkan secara automatik apabila anda menambah sebarang rentetan ke dalam komponen Translate. Perlu diambil perhatian bahawa hanya persekitaran dengan kebenaran read/write pada kunci API akan dapat mencipta rentetan baharu untuk diterjemahkan. Kami mengesyorkan mempunyai persekitaran staging yang tertutup dan selamat di mana anda boleh menguji aplikasi produksi anda menggunakan kunci API seperti itu, menambah rentetan baharu sebelum dilancarkan. Ini akan menghalang sesiapa daripada mencuri kunci API sulit anda, dan berpotensi membengkakkan projek terjemahan anda dengan menambah rentetan baharu yang tidak berkaitan.

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!