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

Wakati dunia inavyokuwa na muunganisho zaidi, ni muhimu zaidi kwa wasanidi wa wavuti kujenga programu zinazoweza kuwahudumia watumiaji kutoka nchi na tamaduni mbalimbali. Njia moja muhimu ya kufanikisha hili ni kupitia ureakesheni wa kimataifa (i18n), ambao unakuwezesha kubadilisha programu yako kwa lugha tofauti, sarafu, na miundo ya tarehe.

Kwenye makala hii, tutaangalia jinsi ya kuongeza ureakesheni wa kimataifa kwenye programu yako ya React Next.js, ikiwa na upakiaji wa upande wa seva. TL;DR: Tazama mfano kamili hapa.

Mwongozo huu ni kwa ajili ya maombi ya Next.js yanayotumia App Router.
Ikiwa unatumia Pages Router, angalia mwongozo huu badala yake.

Hatua ya 1: Sakinisha maktaba ya i18n

Ili kutekeleza uhamishaji lugha katika programu yako ya Next.js, kwanza tutachagua maktaba ya i18n. Kuna maktaba kadhaa maarufu, ikiwa ni pamoja na next-intl. Hata hivyo, katika mfano huu, tutatumia TacoTranslate.

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

Tuweke kupitia npm kwenye terminali 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 tafsiri, na funguo za API zinazohusiana. Unda akaunti hapa. Ni bure, na haitaki upate mkopo wa kadi ya mkopo.

Ndani ya UI ya programu ya TacoTranslate, tengeneza mradi, kisha elekea kwenye kichupo cha funguo za API. Tengeneza ufunguo mmoja wa read na ufunguo mmoja wa read/write. Tutahifadhi hizi kama mabadiliko ya mazingira (environment variables). Ufunguo wa read ndio tunauita public, na ufunguo wa read/write ni secret. Kwa mfano, unaweza kuziaweka kwenye faili ya .env katika mzizi wa mradi wako.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

Tutatoa pia vipengele viwili zaidi vya mazingira: TACOTRANSLATE_DEFAULT_LOCALE na TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Msimbo wa lugha ya chaguo-msingi ya kufallback. Katika mfano huu, tutaweka kuwa en kwa Kiingereza.
• TACOTRANSLATE_ORIGIN: “folda” ambapo mistari yako itawekwa, kama URL ya tovuti yako. Soma zaidi kuhusu origins hapa.

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

Hatua ya 3: Kuweka TacoTranslate

Ili kuunganisha TacoTranslate na programu yako, utahitaji kuunda mteja kwa kutumia funguo za API ulizotumia hapo awali. Kwa mfano, tengeneza faili yenye jina /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 tukitengeneza moja kwa moja TACOTRANSLATE_API_KEY na TACOTRANSLATE_PROJECT_LOCALE hivi karibuni.

Kutengeneza mteja kwenye faili tofauti kunafanya iwe rahisi kuitumia tena baadaye. getLocales ni tu kazi ya kusaidia yenye usimamizi wa makosa uliowekwa ndani. Sasa, tengeneza faili liitwalo /app/[locale]/tacotranslate.tsx, ambapo tutatekeleza mtoaji 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'; inaonyesha kwamba hii ni sehemu ya mteja.

Sasa baada ya mtoaji wa muktadha kuwa tayari, tengeneza faili yenye jina /app/[locale]/layout.tsx, ambayo ni muundo wa mizizi katika programu yetu. Kumbuka kuwa njia hii ina folda inayotumia Dynamic Routes, ambapo [locale] ni parameter ya mabadiliko.

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 kutambua hapa ni kwamba tunatumia parameta yetu ya Dynamic Route [locale] kupata tafsiri za lugha hiyo. Aidha, generateStaticParams inahakikisha kwamba misimbo yote ya lugha uliyozimezesha kwa mradi wako imetayarishwa mapema kwa uwasilishaji.

Sasa, hebu tujenge ukurasa wetu wa kwanza! Unda faili yenye jina /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 revalidate variable inayosema Next.js aaijenge tena ukurasa baada ya sekunde 60, na kuweka tafsiri zako zikiwa za kisasa.

Hatua ya 4: Kutekeleza uoneshaji upande wa seva

TacoTranslate inaunga mkono uonyesho wa upande wa seva. Hii inaboreshwa sana uzoefu wa mtumiaji kwa kuonyesha maudhui yaliyotafsiriwa mara moja, badala ya kuonyesha maudhui yasiyotafsiriwa kwa muda mfupi kwanza. Zaidi ya hayo, tunaweza kupitisha maombi ya mtandao upande wa mteja, kwa sababu tayari tuna tafsiri tunazozihitaji kwa ajili ya ukurasa ambao mtumiaji anauangalia.

Ili kuweka upigaji picha upande wa seva (server side rendering), unda au ubadilishe faili /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};
};

Rekebisha ukaguzi wa isProduction ili kuendana na usanidi wako. Ikiwa true, TacoTranslate itaonyesha ufunguo wa API ya umma. Ikiwa tuko katika mazingira ya ndani, ya majaribio, au ya jukwaa (isProduction is false), tutatumia kitufe cha siri read/write API ili kuhakikisha kuwa mifuatano mipya inatumwa kwa tafsiri.

Ili kuhakikisha kuwa uelekezaji na mwelekeo vinafanya kazi kama inavyotarajiwa, tutahitaji kuunda faili jina lake /middleware.ts. Kutumia Middleware, tunaweza kumwelekeza mtumiaji kurudi kwenye kurasa zinazoonyeshwa kwa lugha anayoitaka.

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 kuki ya locale ili kubadili lugha inayopendelea mtumiaji. Tafadhali angalia msimbo kamili wa mfano kwa mawazo ya jinsi ya kufanya hivyo!

Hatua ya 5: Weka na jaribu!

Tume maliza! React yako sasa itatafsiriwa kiotomatiki unapoongeza mistari yoyote kwenye sehemu ya Translate. Kumbuka kuwa ni mazingira yenye ruhusa za read/write kwenye API key pekee ndiyo yataweza kuunda mistari mipya ya kutafsiriwa. Tunapendekeza kuwa na mazingira ya majaribio yaliyofungwa na salama ambapo unaweza kujaribu programu yako ya uzalishaji kwa kutumia API key kama hiyo, ukiongeza mistari mipya kabla ya kuanza kutumika kwa umma. Hii itazuia mtu yeyote kuiba API key yako ya siri, na pia kuzuia mradi wako wa tafsiri kuongezeka kwa 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!