Penyelesaian terbaik untuk pensuisan antarabangsa (i18n) dalam aplikasi Next.js

Bagaimana ia berfungsi

Apabila dunia menjadi lebih global, adalah semakin penting bagi pembangun web untuk membina aplikasi yang boleh memenuhi keperluan pengguna dari 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, kita akan meneroka cara untuk menambah pengantarabangsaan ke dalam aplikasi React Next.js anda, dengan rendering 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 lihat panduan ini sebagai gantian.

Langkah 1: Pasang perpustakaan i18n

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

TacoTranslate secara automatik menterjemah string 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 membuat akaun TacoTranslate anda, projek terjemahan, dan kunci API yang berkaitan. Cipta akaun di sini. Ia adalah percuma, dan tidak memerlukan anda memasukkan kad kredit.

Dalam antara muka aplikasi TacoTranslate, cipta satu projek, dan navigasi ke tab kekunci API-nya. Cipta satu kekunci read, dan satu kekunci read/write. Kami akan menyimpannya sebagai pembolehubah persekitaran. Kekunci read adalah apa yang kami namakan sebagai public dan kekunci read/write adalah 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 mendedahkan kunci API rahsia read/write kepada persekitaran produksi sisi klien.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Kod lokal lalai sebagai sandaran. Dalam contoh ini, kami akan tetapkan kepada en untuk Bahasa Inggeris.
• TACOTRANSLATE_ORIGIN: "Folder" di mana rentetan anda akan disimpan, seperti URL laman web anda. Baca lebih lanjut tentang 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 kekunci API dari tadi. Sebagai contoh, 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Kita akan secara automatik mentakrifkan TACOTRANSLATE_API_KEY tidak lama lagi.

Mencipta klien dalam fail berasingan memudahkan penggunaan semula kemudian. Sekarang, menggunakan /pages/_app.tsx khas, 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 perluaskan definisi tersebut dengan sifat dan kod dari atas.

Langkah 4: Melaksanakan rendering sisi pelayan

TacoTranslate membenarkan rendering sisi pelayan untuk terjemahan anda. Ini sangat meningkatkan pengalaman pengguna dengan menunjukkan kandungan yang diterjemahkan dengan segera, bukannya sekilas kandungan yang tidak diterjemahkan terlebih dahulu. Selain itu, kita boleh melangkau permintaan rangkaian pada klien, kerana kita sudah mempunyai semua terjemahan yang kita perlukan.

Kita akan mulakan dengan mencipta atau memodifikasi /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 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.

Sehingga kini, kami hanya telah menyediakan aplikasi Next.js dengan senarai bahasa yang disokong. Perkara seterusnya yang akan kita lakukan adalah 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 pada 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 menterjemah rentetan dalam semua komponen React anda.

import {Translate} from 'tacotranslate/react';

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

Langkah 5: Lancarkan dan uji!

Kami sudah selesai! Aplikasi Next.js anda kini akan diterjemahkan secara automatik apabila anda menambah mana-mana string ke dalam komponen Translate. Perlu diambil perhatian bahawa hanya persekitaran dengan kebenaran read/write pada kunci API yang akan dapat mencipta string baru untuk diterjemahkan. Kami mengesyorkan mempunyai persekitaran staging yang tertutup dan selamat di mana anda boleh menguji aplikasi pengeluaran anda dengan kunci API sebegitu, menambah string baru sebelum siaran langsung. Ini akan menghalang sesiapa daripada mencuri kunci API rahsia anda, dan berpotensi membebankan projek terjemahan anda dengan menambah string baru 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!