Jinsi ya kutekeleza utafsiri wa kimataifa katika programu ya Next.js inayotumia App Router

Wakati dunia inavyozidi kuunganishwa, ni muhimu zaidi kwa watengenezaji 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.

Kwenye makala hii, tutaangalia jinsi ya kuongeza utaifa wa kimataifa kwenye programu yako ya React Next.js, kwa kutumia utengenezaji upande wa seva. 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 1: Sakinisha maktaba ya i18n

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

TacoTranslate inatafsiri kiotomatiki maandishi yako kwa lugha yoyote kwa kutumia AI ya kisasa, na inakuondolea kazi ya kuchosha ya kusimamia faili za JSON.

Wacha tuiweke kwa kutumia npm katika terminali yako:

npm install tacotranslate

Hatua ya 2: Unda akaunti ya bure ya TacoTranslate.

Sasa kwa kuwa umesakinisha moduli, ni wakati wa kuunda akaunti yako ya TacoTranslate, mradi wa tafsiri, na funguo za API zinazohusiana. Unda akaunti hapa. Ni bure, na haihitaji kuongeza kadi ya mkopo.

Ndani ya UI ya programu ya TacoTranslate, unda mradi, kisha nenda kwenye kichupo cha funguo za API. Unda ufunguo mmoja read, na ufunguo mmoja read/write. Tutayahifadhi kama vigezo vya mazingira. Funguo la read ndilo tunaloita public, na funguo la read/write ndilo secret. Kwa mfano, unaweza kuyaweka kwenye faili ya .env katika mizizi ya mradi wako.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Hakikisha hauwahi kuvuza ufunguo wa API wa siri read/write katika mazingira ya uzalishaji ya upande wa mteja.

Pia tutaongeza vigezo viwili zaidi vya mazingira: TACOTRANSLATE_DEFAULT_LOCALE na TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Msimbo wa eneo la chaguo-msingi la kurejesha. Katika mfano huu, tutalifanya kuwa en kwa Kiingereza.
• TACOTRANSLATE_ORIGIN: "folda" ambapo maandishi yako yatahifadhiwa, kama vile URL ya tovuti yako. Soma zaidi kuhusu asili 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 kwa kutumia funguo za API ulizotengeneza hapo awali. Kwa mfano, unda faili liitwalo /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;

Tutakuwa tunaweka kiotomatiki TACOTRANSLATE_API_KEY na TACOTRANSLATE_PROJECT_LOCALE hivi karibuni.

Kuunda mteja katika faili tofauti kunafanya iwe rahisi kuitumia tena baadaye. getLocales ni tu kazi ya utiliti yenye udhibiti wa makosa uliowekwa ndani. Sasa, tengeneza faili inayoitwa /app/[locale]/tacotranslate.tsx, ambapo tutaweka 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 kwamba hii ni komponenti ya mteja.

Mtoaji wa muktadha ukiwa tayari, tengeneza faili liitwalo /app/[locale]/layout.tsx, mpangilio mzizi wa programu yetu. Kumbuka kuwa 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>
	);
}

Kitu cha kwanza cha kutambua hapa ni kwamba tunatumia parameter yetu Dynamic Route [locale] kupata tafsiri za lugha hiyo. Zaidi ya hayo, generateStaticParams inahakikisha kuwa misimbo yote ya locale uliowasha kwa mradi wako imeandaliwa awali.

Sasa, 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!" />
	);
}

Kumbuka kigezo cha revalidate ambacho kinaambia Next.js kujenga upya ukurasa baada ya sekunde 60, na kusasisha tafsiri zako ili ziwe za karibuni.

Hatua ya 4: Kutekeleza uwasilishaji wa upande wa seva

TacoTranslate inaunga mkono utayarishaji upande wa seva. Hii inaboresha sana uzoefu wa mtumiaji kwa kuonyesha maudhui yaliyotafsiriwa mara moja, badala ya kuonyesha kwa muda mfupi maudhui ambayo hayajatafsiriwa mwanzoni. Zaidi ya hayo, tunaweza kuruka maombi ya mtandao upande wa mteja, kwa sababu tayari tunazo tafsiri tunazohitaji kwa ukurasa mteja anayeutazama.

Ili kusanidi uonyeshaji upande wa seva, tengeneza au urekebishe /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 ulingane na usanidi wako. Ikiwa true, TacoTranslate itaonyesha ufunguo wa API wa umma. Ikiwa tuko katika mazingira ya ndani, ya majaribio, au ya kuandaa (staging) (isProduction is false), tutatumia ufunguo wa API wa siri read/write ili kuhakikisha vipengele vipya vya maandishi vinatumwa kwa tafsiri.

Ili kuhakikisha upangaji wa njia na uelekezaji vinavyofanya kazi kama inavyotarajiwa, tutahitaji kuunda faili liitwalo /middleware.ts. Kwa kutumia Middleware, tunaweza kuelekeza watumiaji kwenye kurasa zinazowasilishwa 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 mujibu wa nyaraka za Middleware ya Next.js.

Kwa upande wa mteja, unaweza kubadilisha kuki ya locale ili kubadilisha lugha inayopendwa na mtumiaji. Tafadhali angalia msimbo kamili wa mfano ili kupata mawazo kuhusu jinsi ya kufanya hivyo!

Hatua ya 5: Zindua na jaribu!

Tumemaliza! Programu yako ya React sasa itatafsirika moja kwa moja unapoongeza mistari yoyote kwenye sehemu ya Translate. Kumbuka kuwa ni mazingira tu yenye ruhusa za read/write kwenye funguo za API zitakazoweza kuunda mistari mipya ya kutafsiriwa. Tunapendekeza uwe na mazingira ya majaribio yaliyofungwa na salama ambapo unaweza kujaribu programu yako ya uzalishaji ukiwa na funguo ya API kama hiyo, kuongeza mistari mipya kabla ya kuanzisha rasmi. Hii itazuia mtu yeyote kuiba funguo zako za siri za API, na kwa uwezekano kueneza mradi wako wa tafsiri kwa kuongeza mistari mipya isiyo husiana.

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!