Penyelesaian terbaik untuk pengantarabangsaan (i18n) dalam aplikasi Next.js

Bagaimana ia berfungsi

Apabila dunia menjadi semakin global, adalah semakin penting bagi pembangun web untuk membina aplikasi yang boleh memenuhi keperluan pengguna daripada negara dan budaya yang berbeza. 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, kita akan meneroka cara menambah pengantarabangsaan kepada aplikasi React Next.js anda, dengan penyajian di sisi pelayan. TL;DR: Lihat contoh penuh di sini.

Panduan ini 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 terlebih dahulu memilih pustaka i18n. Terdapat beberapa pustaka popular, termasuk next-intl. Walau bagaimanapun, dalam contoh ini, kami akan menggunakan TacoTranslate.

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

Mari pasang ia menggunakan npm dalam terminal anda:

npm install tacotranslate

Langkah 2: Daftar akaun TacoTranslate percuma

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

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

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Pastikan anda tidak pernah membocorkan 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 untuk 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 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 sebelum ini. 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 sekejap lagi.

Membuat klien dalam fail berasingan memudahkan penggunaannya 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 tersuai, sila kembangkan definisi tersebut dengan sifat-sifat dan kod di atas.

Langkah 4: Melaksanakan rendering di sisi pelayan

TacoTranslate membolehkan rendering sisi pelayan untuk terjemahan anda. Ini amat meningkatkan pengalaman pengguna dengan memaparkan kandungan yang telah diterjemahkan serta-merta, bukannya paparan sekejap kandungan yang belum diterjemah terlebih dahulu. Selain itu, kita boleh mengelakkan permintaan rangkaian pada klien, kerana kita sudah mempunyai semua terjemahan yang diperlukan.

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

Ubah pemeriksaan isProduction mengikut tetapan anda. Jika true, TacoTranslate akan memaparkan kunci API awam. Jika kami berada dalam persekitaran tempatan, ujian, atau staging (isProduction is false), kami akan menggunakan kunci API rahsia read/write untuk memastikan rentetan baru dihantar untuk penterjemahan.

Sehingga kini, kami hanya menyediakan aplikasi Next.js dengan senarai bahasa yang disokong. Perkara seterusnya yang akan kita 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 terkini.

Untuk menggunakan mana-mana fungsi ini 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 sepatutnya boleh menggunakan komponen Translate untuk menerjemahkan teks dalam semua komponen React anda.

import {Translate} from 'tacotranslate/react';

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

Langkah 5: Lancarkan dan uji!

Selesai! Aplikasi Next.js anda kini akan diterjemahkan secara automatik apabila anda menambahkan sebarang rentetan kepada komponen Translate. Perlu diingat bahawa hanya persekitaran yang mempunyai 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 pengeluaran anda dengan kunci API sebegitu, menambah rentetan baharu sebelum dilancarkan. Ini akan menghalang sesiapa daripada mencuri kunci API rahsia 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 App 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!