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

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

Dalam artikel ini, kita akan meneroka cara menambah internationalization ke dalam aplikasi React Next.js anda, dengan server side rendering. TL;DR: Lihat contoh penuh 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 perpustakaan i18n

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

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

Jom pasang menggunakan npm dalam terminal anda:

npm install tacotranslate

Langkah 2: Cipta akaun TacoTranslate percuma

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

Dalam antara muka aplikasi TacoTranslate, cipta satu projek, dan navigasi ke tab kekunci API. Cipta satu kekunci read, dan satu kekunci read/write. Kami akan menyimpannya sebagai pembolehubah persekitaran. Kekunci read adalah apa yang kami sebut sebagai public dan kekunci read/write adalah secret. Contohnya, anda boleh menambahkannya ke dalam fail .env di akar projek anda.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

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

• TACOTRANSLATE_DEFAULT_LOCALE: Kod lokal lalai sebagai gantian. 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 mengenai asal usul di sini.

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

Langkah 3: Menyediakan TacoTranslate

Untuk mengintegrasikan TacoTranslate dengan aplikasi anda, anda perlu mencipta klien menggunakan kunci API dari sebelumnya. Contohnya, cipta 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.

Mewujudkan klien dalam fail yang berasingan menjadikannya mudah untuk digunakan semula kemudian. getLocales hanyalah fungsi utiliti dengan beberapa pengendalian ralat terbina dalam. Kini, 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 yang kini sudah siap, buat satu fail bernama /app/[locale]/layout.tsx, iaitu susun atur akar dalam aplikasi kami. Perhatikan bahawa laluan ini mempunyai folder yang menggunakan Dynamic Routes, di mana [locale] adalah 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 kita menggunakan parameter Dynamic Route kita iaitu [locale] untuk mendapatkan terjemahan bagi bahasa tersebut. Selain itu, generateStaticParams memastikan semua kod locale yang anda telah aktifkan untuk projek anda telah dipra-render.

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 sisi pelayan

TacoTranslate menyokong rendering sisi pelayan. Ini secara ketara meningkatkan pengalaman pengguna dengan menunjukkan kandungan yang diterjemah serta-merta, bukannya paparan sekejap kandungan yang belum diterjemah terlebih dahulu. Selain itu, kami boleh melangkau permintaan rangkaian di pihak klien, kerana kami sudah mempunyai terjemahan yang diperlukan untuk halaman yang dilihat oleh pengguna.

Untuk menyediakan rendering 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 suai semak isProduction agar sesuai dengan persediaan anda. Jika true, TacoTranslate akan memaparkan kunci API awam. Jika kami berada dalam persekitaran tempatan, ujian atau pementasan (isProduction is false), kami akan menggunakan kunci API read/write rahsia untuk memastikan rentetan baharu dihantar untuk terjemahan.

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

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

Langkah 5: Terapkan dan uji!

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

Pastikan untuk melihat contoh lengkap di profil GitHub kami. Di sana, anda juga akan menemui contoh bagaimana melakukan ini menggunakan Pages Router ! Jika anda menghadapi sebarang masalah, jangan ragu untuk menghubungi kami, dan kami akan dengan senang hati membantu.

TacoTranslate membolehkan anda menyesuaikan aplikasi React anda secara automatik dengan cepat ke dan dari mana-mana bahasa. Mulakan hari ini!