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

Kadiri dunia inavyokuwa ya kimataifa zaidi, ni muhimu zaidi kwa watengenezaji wa wavuti kujenga programu ambazo zinaweza kuwahudumia watumiaji kutoka nchi na tamaduni mbalimbali. Moja ya njia kuu za kufanikisha hili ni kupitia kuwezesha matumizi ya lugha mbalimbali (i18n), ambayo inakuwezesha kurekebisha programu yako kwa lugha tofauti, sarafu, na muundo wa tarehe.

Katika makala hii, tutajifunza jinsi ya kuongeza msaada wa lugha nyingi (i18n) kwenye programu yako ya React Next.js, pamoja na upigaji ukurasa upande wa seva. TL;DR: Tazama mfano kamili hapa.

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

Hatua ya 1: Sakinisha maktaba ya i18n

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

TacoTranslate inatafsiri moja kwa moja mistari yako (strings) kwa lugha yoyote kwa kutumia AI ya kisasa, na inakuondolea kazi ya kusimamia faili za JSON.

Sakinisha kwa kutumia npm kwenye terminali 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 haihitaji uongeze kadi ya mkopo.

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

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Hakikisha hauwahi kufichua ufunguo wa API wa siri read/write kwenye mazingira ya uzalishaji upande wa mteja.

Tutaongeza pia vigezo viwili zaidi vya mazingira: TACOTRANSLATE_DEFAULT_LOCALE na TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Msimbo wa eneo (locale) utakaotumika kama chaguo la kimsingi. Katika mfano huu, tutauweka kuwa en kwa Kiingereza.
• TACOTRANSLATE_ORIGIN: “folda” ambapo mistari (strings) zako zitawekwa, 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 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 kwa kiotomatiki TACOTRANSLATE_API_KEY na TACOTRANSLATE_PROJECT_LOCALE hivi punde.

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

Sasa kwa kuwa mtoaji wa muktadha yuko tayari, unda faili iitwayo /app/[locale]/layout.tsx, mpangilio wa mzizi katika programu yetu. Kumbuka kwamba njia hii ina saraka 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 kukumbuka hapa ni kwamba tunatumia parameter yetu Dynamic Route [locale] ili kupata tafsiri za lugha hiyo. Zaidi ya hayo, generateStaticParams inahakikisha kuwa nambari zote za locale ulizowezesha kwa mradi wako zimetayarishwa 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!" />
	);
}

Kumbuka kigezo revalidate kinachoambia Next.js kujenga ukurasa upya baada ya sekunde 60, na kusasisha tafsiri zako.

Hatua ya 4: Kutekeleza uonyeshaji wa upande wa seva

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

Ili kusanidi utayarishaji 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 uendane na usanidi wako. Ikiwa true, TacoTranslate itaonyesha ufunguo wa API wa umma. Ikiwa tuko katika mazingira ya ndani, ya majaribio, au ya kuandalia (isProduction is false), tutatumia ufunguo wa siri read/write wa API ili kuhakikisha misimbo mipya ya maandishi inatumwa kwa ufasiri.

Ili kuhakikisha kwamba upitishaji wa njia na uelekezaji upya vinavyofanya kazi kama vinavyotarajiwa, tutahitaji kuunda faili iitwayo /middleware.ts. Kwa kutumia Middleware, tunaweza kuwaelekeza watumiaji kwa 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 kulingana na nyaraka za Middleware ya Next.js.

Kwa upande wa mteja, unaweza kubadilisha kuki locale ili kubadilisha lugha anayopendelea mtumiaji. Tafadhali angalia msimbo kamili wa mfano kwa mawazo juu ya jinsi ya kufanya hivyo!

Hatua ya 5: Weka kwenye uzalishaji na jaribu!

Tumeimaliza! Programu yako ya React sasa itatafsiriwa kwa otomatiki unapoongeza maandishi yoyote kwenye sehemu ya Translate. Kumbuka kwamba mazingira yanayokuwa na ruhusa za read/write kwenye funguo ya API ndiyo yatakayoweza kuunda maandishi mapya ya kutafsiriwa. Tunapendekeza kuwa na mazingira ya staging yaliyofungwa na yaliyo salama ambapo unaweza kujaribu programu yako ya uzalishaji kwa kutumia funguo ya API kama hiyo, ukiongeza maandishi mapya kabla ya kuingia mtandaoni. Hii itaizuia mtu yeyote kuiba funguo yako ya API ya siri, na pengine kusababisha mradi wako wa tafsiri kuzidiwa kwa kuongeza maandishi mapya yasiyohusiana.

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!