L-aħjar soluzzjoni għall-internazzjonalizzazzjoni (i18n) f'applikazzjonijiet Next.js

Kif jaħdem

Hekk kif id-dinja ssir aktar globalizzata, huwa dejjem aktar importanti għall-iżviluppaturi tal-web li joħolqu applikazzjonijiet li jistgħu jilqgħu lill-utenti minn pajjiżi u kulturi differenti. Wieħed mill-modi ewlenin biex jintlaħaq dan hu permezz tal-internazzjonalizzazzjoni (i18n), li tippermettilek tadatta l-applikazzjoni tiegħek għal lingwi differenti, muniti u formati tad-data.

F'dan it-tutorja, ser neżaminaw kif iżżid internazzjonalizzazzjoni mal-applikazzjoni React Next.js tiegħek, b'rendering fuq is-server. TL;DR: Ara l-eżempju sħiħ hawn.

Din il-gwida hija għall-applikazzjonijiet Next.js li qed jużaw il-Pages Router.
Jekk qed tuża l-App Router, jekk jogħġbok, ara din il-gwida minflok.

Pass 1: Installa librerija ta' i18n

Biex nimplimentaw l-internazzjonalizzazzjoni fl-applikazzjoni Next.js tiegħek, l-ewwel nagħżlu librerija i18n. Hemm diversi libreriji popolari, inklużi next-intl. Madankollu, f'dan l-eżempju, se nużaw TacoTranslate.

TacoTranslate jittraduċi awtomatikament l-strings tiegħek għal kwalunkwe lingwa billi juża AI avvanzata, u jiffrankak mill-immaniġġjar tedjuż tal-fajls JSON.

Ejjew ninstallawh billi nużaw npm fit-terminal tiegħek:

npm install tacotranslate

Pass 2: Oħloq kont TacoTranslate b'xejn

Issa li għandek il-modul installat, wasal iż-żmien li toħloq kont fuq TacoTranslate, proġett ta' traduzzjoni, u ċwievet API assoċjati. Oħloq kont hawn. Huwa b'xejn, u ma jeħtieġlekx li żżid karta ta' kreditu.

Fil-UI tal-applikazzjoni TacoTranslate, oħloq proġett u mur fit-tab tal-API keys tagħha. Oħloq ċavetta waħda read u ċavetta oħra read/write. Se ninżluhom bħala varjabbli tal-ambjent. Iċ-ċavetta read hija dak li nsejħu public, u ċ-ċavetta read/write hija secret. Per eżempju, tista' żżidhom fil-fajl .env fir-root tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tirrilaxxa s-sigriet read/write ċavetta tal-API lill-ambjenti ta' produzzjoni fuq in-naħa tal-klijent.

Se nżidu wkoll żewġ varjabbli tal-ambjent oħrajn: TACOTRANSLATE_DEFAULT_LOCALE u TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi predefinit tal-lokalità li jintuża bħala fallback. F'dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jinżammu t-testi tiegħek, bħal pereżempju l-URL tas-sit tiegħek. Aqra aktar dwar origins hawn.

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

Pass 3: Issettjar ta' TacoTranslate

Biex tintegra TacoTranslate fl-applikazzjoni tiegħek, trid toħloq client li juża ċwievet tal-API msemmija qabel. Per eżempju, oħloq fajl imsejjaħ /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;

Dalwaqt se niddedefinixxu awtomatikament TACOTRANSLATE_API_KEY.

Il-ħolqien tal-klijent f’fajl separat jagħmilha aktar faċli li jintuża mill-ġdid aktar tard. Issa, billi tuża /pages/_app.tsx personalizzat, se nżidu l-fornitur 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>
	);
}

Jekk diġà għandek pageProps u _app.tsx personalizzati, jekk jogħġbok estendi id-definizzjoni bil-propjetajiet u l-kodiċi msemmija hawn fuq.

Pass 4: Implementazzjoni tar-rendering fuq in-naħa tas-server

TacoTranslate jippermetti r-rendering fuq in-naħa tas-server tat-traduzzjonijiet tiegħek. Dan ittejjeb b'mod sinifikanti l-esperjenza tal-utent billi juri l-kontenut tradott immedjatament, minflok mument inizjali ta' kontenut mhux tradott. Barra minn hekk, nistgħu nevitaw talbiet tan-netwerk fuq il-klijent, għax diġà għandna t-traduzzjonijiet kollha li għandna bżonn.

Nibdew billi noħolqu jew nimmodifikaw /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'),
	});
};

Aġġusta l-verifika isProduction biex taqbel mal‑konfigurazzjoni tiegħek. Jekk true, TacoTranslate se juri iċ‑ċavetta API pubblika. Jekk ninsabu f'ambjent lokali, ta' test, jew ta' staging (isProduction is false), se nużaw iċ‑ċavetta API sigrieta read/write biex niżguraw li s‑strings ġodda jintbagħtu għall‑traduzzjoni.

Sa issa, konna biss waqqafna l-applikazzjoni Next.js b'lista ta' lingwi appoġġati. Il-pass li jmiss hu li nġibu t-traduzzjonijiet għal kull paġna tiegħek. Biex tagħmel dan, se tuża jew getTacoTranslateStaticProps jew getTacoTranslateServerSideProps skont ir-rekwiżiti tiegħek.

Dawn il-funzjonijiet jieħdu tliet argumenti: oġġett wieħed Next.js Static Props Context, konfigurazzjoni għal TacoTranslate, u proprjetajiet opzjonali ta' Next.js. Nota li revalidate fuq getTacoTranslateStaticProps huwa stabbilit għal 60 b'mod predefinit, sabiex it-traduzzjonijiet tiegħek jibqgħu aġġornati.

Biex tuża kwalunkwe minn dawn il-funzjonijiet f'paġna, ejja nassumu li għandek fajl ta' paġna bħal /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!"/>;
}

Issa għandek tkun tista' tuża l-komponent Translate biex tittraduċi stringijiet fi ħdan il-komponenti kollha ta' React tiegħek.

import {Translate} from 'tacotranslate/react';

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

Pass 5: Ippubblika u ittestja!

Għamilna! L-applikazzjoni Next.js tiegħek issa se tittraduċi awtomatikament meta żżid kwalunkwe string fi komponent Translate. Innota li biss l-ambjenti b'permessi read/write fuq il-key tal-API jkunu jistgħu joħolqu strings ġodda biex jittraduċu. Nirrakkomandaw li jkollok ambjent ta' staging magħluq u sigur fejn tista' tittestja l-applikazzjoni tal-produzzjoni tiegħek bi-key tal-API bħal dik, u żżid strings ġodda qabel tmur live. Dan se jipprevjeni li xi ħadd xi ħadd jisraq is-sigriet tal-key tal-API tiegħek, u potenzjalment jimla l-proġett tat-traduzzjoni tiegħek billi jżid strings ġodda mhux relatati.

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!