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

Wakati dunia inapozidi kuunganishwa, inakuwa muhimu zaidi kwa waendelezaji wa wavuti kujenga programu zinazoweza kuwahudumia watumiaji kutoka nchi na tamaduni mbalimbali. Moja ya njia kuu za kufanikisha hili ni kupitia utekelezaji wa kimataifa (internationalization, i18n), unaokuruhusu kurekebisha programu yako kwa lugha tofauti, sarafu, na miundo ya tarehe.

Katika makala hii, tutachunguza jinsi ya kuongeza utekelezaji wa kimataifa kwenye programu yako ya React Next.js, pamoja na upakiaji 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 kuwezesha matumizi ya lugha nyingi (internationalization) katika programu yako ya Next.js, kwanza tuta-chagua maktaba ya i18n. Kuna maktaba kadhaa maarufu, ikiwa ni pamoja na next-intl. Hata hivyo, katika mfano huu, tutatumia TacoTranslate.

TacoTranslate itatafsiri kwa kiotomatiki misemo yako kwa lugha yoyote kwa kutumia AI ya kiwango cha juu, na inakuokoa kutoka kwa usimamizi wa kuchosha wa faili za JSON.

Hebu tuiweke kwa kutumia npm kwenye terminal yako:

npm install tacotranslate

Hatua ya 2: Unda akaunti ya bure ya TacoTranslate

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 kuongeza kadi ya mkopo.

Ndani ya UI ya programu ya TacoTranslate, tengeneza mradi, kisha nenda kwenye kichupo chake cha vifunguo vya API. Unda funguo moja read, na funguo moja read/write. Tutaziweka kama vigezo vya mazingira. Funguo read ndicho tunachokiita public na funguo read/write ndicho secret. Kwa mfano, unaweza kuyaongeza kwenye faili ya .env katika mzizi wa mradi wako.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Hakikisha usiwahi kufichua ufunguo wa API wa siri read/write kwa mazingira ya uzalishaji upande wa mteja.

Pia tutaongeza vigezo viwili vya mazingira: TACOTRANSLATE_DEFAULT_LOCALE na TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Msimbo wa lahaja ya chaguo-msingi. Katika mfano huu, tutaweka kuwa en kwa Kiingereza.
• TACOTRANSLATE_ORIGIN: “folda” ambapo matini zako zitatunzwa, 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 ulizozitengeneza hapo awali. Kwa mfano, tengeneza 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;

Tutaziweka 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 msaada tu inayotoa utunzaji wa makosa uliojengewa ndani. Sasa, tengeneza faili iitwayo /app/[locale]/tacotranslate.tsx, ambapo tutekeleze 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'; inayoonyesha kuwa hii ni komponenti ya mteja.

Kwa kuwa mtoaji wa muktadha sasa tayari, unda faili iitwayo /app/[locale]/layout.tsx, muundo wa 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>
	);
}

Kitu cha kwanza cha kuzingatia hapa ni kwamba tunatumia kigezo chetu Dynamic Route [locale] kupata tafsiri za lugha hiyo. Zaidi ya hayo, generateStaticParams inahakikisha kwamba nambari zote za locale ulizowasha kwa mradi wako zimetayarishwa awali.

Sasa, hebu tujenge ukurasa wetu wa kwanza! Unda faili iliyoitwa /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 ambacho kinaeleza Next.js kujenga ukurasa upya baada ya sekunde 60, na kuhakikisha tafsiri zako zinabaki za kisasa.

Hatua ya 4: Kutekeleza uundaji wa ukurasa upande wa seva

TacoTranslate inasaidia uonyeshaji unaofanywa 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 mwanzoni. Zaidi ya hayo, tunaweza kuepuka kufanya maombi ya mtandao upande wa mteja, kwa sababu tayari tuna tafsiri tunazohitaji kwa ukurasa mtumiaji 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 uendane na usanidi wako. Ikiwa true, TacoTranslate itaonyesha ufunguo wa API wa umma. Ikiwa tuko katika mazingira ya ndani, ya mtihani, au ya staging (isProduction is false), tutatumia ufunguo wa siri read/write wa API ili kuhakikisha misemo mipya inatumwa kwa tafsiri.

Ili kuhakikisha upitishaji wa njia na urejeshaji vinavyofanya kazi kama inavyotarajiwa, tutahitaji kuunda faili liitwalo /middleware.ts. Kwa kutumia Middleware, tunaweza kuelekeza watumiaji kwa kurasa zinazoonyeshwa kwa lugha wanayoipendelea.

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 za Next.js.

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

Hatua ya 5: Weka kwenye uzalishaji na jaribu!

Tumeisha! Programu yako ya React sasa itatafsiriwa kiotomatiki unapoongeza nyuzi zozote za maandishi kwenye komponenti ya Translate. Kumbuka kwamba mazingira pekee yaliyo na ruhusa za read/write kwenye ufunguo wa API ndizo zitakazoweza kuunda nyuzi mpya za kutafsiriwa. Tunapendekeza kuwa na mazingira ya majaribio (staging) yaliyofungwa na salama, ambapo unaweza kujaribu programu yako ya uzalishaji kwa kutumia ufunguo wa API kama huo, ukiongeza nyuzi mpya kabla ya kwenda mtandaoni. Hii itazuia mtu yeyote mtu yeyote kuiba ufunguo wako wa siri wa API, na inaweza kupelekea mradi wako wa utafsiri kupanuka kupita kiasi kwa kuongeza nyuzi 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!