Jinsi ya kutekeleza i18n (internationalization) katika programu ya Next.js inayotumia App Router

Wakati dunia inavyoendelea kuwa ya kimataifa zaidi, inazidi kuwa muhimu kwa waendelezaji wa wavuti kujenga programu zinazoweza kuwahudumia watumiaji kutoka nchi na tamaduni mbalimbali. Moja ya njia muhimu za kufanikisha hili ni kupitia utaifa wa kimataifa (i18n), ambao unakuwezesha kubadilisha programu yako kwa lugha tofauti, sarafu, na miundo ya tarehe.

Katika makala hii, tutachunguza jinsi ya kuongeza utaifa wa kimataifa kwenye programu yako ya React Next.js, kwa kutumia server-side rendering. TL;DR: Tazama mfano kamili hapa.

Mwongozo huu ni kwa programu za Next.js zinazotumia App Router.
Ikiwa unatumia Pages Router, tazama mwongozo huu badala yake.

Hatua ya 1: Sakinisha maktaba ya i18n

Ili kutekeleza uanzishaji wa kimataifa wa lugha (internationalization) katika programu yako ya Next.js, kwanza tutachagua maktaba ya i18n. Kuna maktaba kadhaa maarufu, zikiwemo next-intl. Katika mfano huu, hata hivyo, tutatumia TacoTranslate.

TacoTranslate hufasiri moja kwa moja mistari yako ya maandishi kwa lugha yoyote kwa kutumia AI ya kisasa, na inakuondolea mzigo wa kusimamia faili za JSON.

Tuweke kwa kutumia npm kwenye terminal yako:

npm install tacotranslate

Hatua ya 2: Unda akaunti ya TacoTranslate ya bure

Sasa baada ya kusakinisha moduli, ni wakati wa kuunda akaunti yako ya TacoTranslate, mradi wa utafsiri, na funguo za API zinazohusiana. Unda akaunti hapa. Ni bure, na hauhitaji kuongeza kadi ya mkopo.

Ndani ya UI ya programu ya TacoTranslate, tengeneza mradi, kisha nenda kwenye kichupo chake cha funguo za API. Tengeneza ufunguo mmoja read na ufunguo mmoja read/write. Tutayahifadhi kama vigezo vya mazingira. Ufunguo read ndiyo tunaoita public, na ufunguo read/write ni secret. Kwa mfano, unaweza kuyaweka kwenye faili .env katika mzizi wa mradi wako.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Hakikisha haufichui kamwe ufunguo wa API wa siri read/write kwa mazingira ya uzalishaji ya upande wa mteja.

Pia tutaongeza vigezo viwili vya mazingira: TACOTRANSLATE_DEFAULT_LOCALE na TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Msimbo wa lahaja ya chaguo-msingi ya kirejeshi. Katika mfano huu, tutaweka kuwa en kwa Kiingereza.
• TACOTRANSLATE_ORIGIN: “folda” ambapo strings zako zitahifadhiwa, kama vile URL ya tovuti yako. Soma zaidi kuhusu origins hapa.

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

Hatua ya 3: Kusanidi TacoTranslate

Ili kuunganisha TacoTranslate na programu yako, utahitaji kuunda mteja ukitumia funguo za API zilizo hapo awali. Kwa mfano, unda faili iitwayo /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;

Tutabainisha kiotomatiki TACOTRANSLATE_API_KEY na TACOTRANSLATE_PROJECT_LOCALE hivi karibuni.

Kuunda mteja katika faili tofauti kunafanya iwe rahisi kuitumia tena baadaye. getLocales ni kazi ya utiliti tu yenye usindikaji wa makosa uliojengewa ndani. Sasa, tengeneza faili iitwayo /app/[locale]/tacotranslate.tsx, ambapo tutaweka utekelezaji wa mtoa huduma wa 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>
	);
}

Kumbuka 'use client'; ikionyesha kuwa hii ni komponenti ya mteja.

Kwa kuwa mtoaji wa muktadha sasa ume tayari, unda faili iitwayo /app/[locale]/layout.tsx, mpangilio mzizi katika programu yetu. Kumbuka kwamba njia hii ina folda inayotumia Dynamic Routes, ambapo [locale] ni kigezo kinachobadilika.

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

Jambo la kwanza la kuzingatia hapa ni kwamba tunatumia kigezo chetu cha Dynamic Route [locale] ili kupata tafsiri za lugha hiyo. Aidha, generateStaticParams inahakikisha kwamba nambari zote za locale ulizowezesha kwa mradi wako zinatayarishwa mapema.

Sasa, hebu tujenge ukurasa wetu wa kwanza! Unda faili iitwayo /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!" />
	);
}

Zingatia kigezo revalidate kinachoambia Next.js kujenga upya ukurasa baada ya sekunde 60, na kusasisha tafsiri zako ili ziwe za kisasa.

Hatua ya 4: Kutekeleza uonyesho upande wa seva

TacoTranslate inasaidia uonyeshaji wa upande wa seva. Hii inaboresha kwa kiasi kikubwa uzoefu wa mtumiaji kwa kuonyesha maudhui yaliyotafsiriwa mara moja, badala ya kuonekana kwa muda mfupi kwa maudhui yasiyotafsiriwa. Zaidi ya hayo, tunaweza kuepuka maombi ya mtandao kwa upande wa mteja, kwa sababu tayari tuna tafsiri tunazohitaji kwa ukurasa ambao mtumiaji anautazama.

Ili kusanidi uonyesaji upande wa seva, unda au badilisha /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};
};

Badilisha ukaguzi wa isProduction ili uendane na usanidi wako. Ikiwa true, TacoTranslate itaonyesha ufunguo wa API wa umma. Ikiwa tuko katika mazingira ya ndani, ya mtihani, au ya maandalizi (isProduction is false), tutatumia ufunguo wa siri read/write ili kuhakikisha mistari mipya imetumwa kwa tafsiri.

Ili kuhakikisha upangaji wa njia na uelekeaji vinavyofanya kazi kama ilivyotarajiwa, tutahitaji kuunda faili iitwayo /middleware.ts. Kwa kutumia Middleware, tunaweza kuwaelekeza watumiaji kwenye kurasa zinazoonyeshwa kwa lugha wanayopendelea.

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

Hakikisha kusanidi matcher kwa kuzingatia nyaraka za Middleware za Next.js.

Kwenye upande wa mteja, unaweza kubadilisha cookie ya locale ili kubadilisha lugha inayopendwa na mtumiaji. Tafadhali tazama msimbo wa mfano kamili kwa mawazo juu ya jinsi ya kufanya hivyo!

Hatua ya 5: Weka kwenye uzalishaji na ujaribu!

Tumemaliza! Programu yako ya React sasa itatafsiriwa moja kwa moja unapoongeza mfuatano wowote wa herufi kwenye sehemu ya Translate. Kumbuka kuwa mazingira pekee yenye ruhusa za read/write kwenye ufunguo wa API ndiyo yatakayoweza kuunda mfuatano mpya wa herufi za kutafsiriwa. Tunapendekeza kuwa na mazingira ya staging yaliyofungwa na yaliyo salama ambapo unaweza kujaribu programu yako ya uzalishaji kwa kutumia ufunguo wa API wa aina hiyo, ukiongeza mfuatano mpya wa herufi kabla ya kuingia mtandaoni. Hii itazuia mtu yeyote mtu yeyote kuiba ufunguo wako wa siri wa API, na kwa uwezekano kusababisha mradi wako wa tafsiri kujaa kwa kuongeza mfuatano mpya zisizohusiana.

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 Pages 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!