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

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

Dalam tutorial ini, kami akan meneroka cara untuk menambah pengantarabangsaan ke dalam aplikasi React Next.js anda, dengan render sisi pelayan. TL;DR: Lihat contoh penuh di sini.

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

Langkah 1: Pasang pustaka i18n

Untuk melaksanakan pengantarabangsaan dalam aplikasi Next.js anda, kita akan memilih perpustakaan i18n terlebih dahulu. Terdapat beberapa perpustakaan popular, termasuk next-intl. Walau bagaimanapun, dalam contoh ini, kita akan menggunakan TacoTranslate.

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

Mari pasang ia menggunakan npm di terminal anda:

npm install tacotranslate

Langkah 2: Buat akaun TacoTranslate percuma

Sekarang anda telah memasang modul itu, masanya untuk membuat akaun TacoTranslate anda, projek terjemahan, dan kunci API yang berkaitan. Buat akaun di sini. Ia percuma, dan tidak memerlukan anda menambah kad kredit.

Dalam antara muka aplikasi TacoTranslate, buat satu projek, dan pergi ke tab kekunci API. Buat satu kekunci read, dan satu kekunci read/write. Kami akan menyimpannya sebagai pembolehubah persekitaran. Kekunci read adalah apa yang kami panggil public, dan kekunci read/write adalah secret. Sebagai contoh, anda boleh menambahkannya ke dalam fail .env di direktori root 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 sisi klien.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Kod lokal sandaran lalai. Dalam contoh ini, kami akan menetapkannya kepada en untuk Bahasa Inggeris.
• TACOTRANSLATE_ORIGIN: “folder” di mana teks anda akan disimpan, seperti URL laman web anda. Baca lebih lanjut tentang origins 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 diberikan sebelumnya. Sebagai contoh, buat 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Kami akan secara automatik mendefinisikan TACOTRANSLATE_API_KEY tidak lama lagi.

Mencipta klien dalam fail yang berasingan menjadikannya lebih mudah untuk digunakan semula kemudian. Sekarang, dengan menggunakan /pages/_app.tsx tersuai, kita akan menambah penyedia TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Jika anda sudah mempunyai pageProps dan _app.tsx yang tersuai, sila kembangkan definisi tersebut dengan properti dan kod yang dinyatakan di atas.

Langkah 4: Melaksanakan penyajian sisi pelayan

TacoTranslate menyokong rendering di sisi pelayan bagi terjemahan anda. Ini sangat meningkatkan pengalaman pengguna dengan memaparkan kandungan yang diterjemahkan serta-merta, bukannya menunjukkan kilasan kandungan yang belum diterjemah terlebih dahulu. Selain itu, permintaan rangkaian pada pihak klien boleh diabaikan kerana semua terjemahan yang diperlukan sudah tersedia.

Kita akan mula dengan membuat atau mengubah /next.config.js.

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

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Sesuaikan 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 baharu dihantar untuk diterjemahkan.

Setakat ini, kami hanya menyediakan aplikasi Next.js dengan senarai bahasa yang disokong. Perkara seterusnya yang akan kami lakukan ialah mendapatkan terjemahan untuk semua halaman anda. Untuk melakukan itu, anda akan menggunakan sama ada getTacoTranslateStaticProps atau getTacoTranslateServerSideProps berdasarkan keperluan anda.

Fungsi-fungsi ini mengambil tiga argumen: Satu objek Next.js Static Props Context, konfigurasi untuk TacoTranslate, dan sifat Next.js pilihan. Perhatikan bahawa revalidate pada getTacoTranslateStaticProps ditetapkan kepada 60 secara lalai, supaya terjemahan anda sentiasa dikemas kini.

Untuk menggunakan mana-mana fungsi dalam sebuah halaman, anggap anda mempunyai fail halaman seperti /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

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

Anda kini boleh menggunakan komponen Translate untuk menterjemahkan rentetan dalam semua komponen React anda.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Langkah 5: Lancar dan uji!

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

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

TacoTranslate membolehkan anda melokalkan aplikasi React anda secara automatik dengan cepat ke dan dari lebih 75 bahasa. Mulakan hari ini!