Si të implementoni ndërkombëtarizimin në një aplikacion Next.js që përdor App Router

Ndërsa bota bëhet më e globalizuar, bëhet gjithnjë e më e rëndësishme për zhvilluesit e uebit të krijojnë aplikacione që i përshtaten përdoruesve nga vende dhe kultura të ndryshme. Një nga mënyrat kryesore për ta arritur këtë është përmes ndërkombëtarizimit (i18n), i cili ju lejon të përshtatni aplikacionin tuaj për gjuhë, monedha dhe formatet e datave të ndryshme.

Në këtë artikull, do të eksplorojmë se si të shtoni ndërkombëtarizimin në aplikacionin tuaj React Next.js, me rendërim në anën e serverit. TL;DR: Shihni shembullin e plotë këtu.

Ky udhëzues është për aplikacionet Next.js që përdorin App Router.
Nëse po përdorni Pages Router, shihni këtë udhëzues në vend të tij.

Hapi 1: Instaloni një bibliotekë i18n

Për të zbatuar ndërkombëtarizimin në aplikacionin tuaj Next.js, së pari do të zgjedhim një bibliotekë i18n. Ekzistojnë disa biblioteka të njohura, përfshirë next-intl. Megjithatë, në këtë shembull do të përdorim TacoTranslate.

TacoTranslate përkthen automatikisht vargjet tuaja në çdo gjuhë duke përdorur inteligjencën artificiale më të fundit, dhe ju çliron nga menaxhimi i lodhshëm i skedarëve JSON.

Le ta instalojmë duke përdorur npm në terminalin tuaj:

npm install tacotranslate

Hapi 2: Krijoni një llogari falas në TacoTranslate

Tani që keni instaluar modulin, është koha të krijoni llogarinë tuaj TacoTranslate, një projekt përkthimi dhe çelësat API përkatës. Krijoni një llogari këtu. Është falas, dhe nuk kërkon të shtoni një kartë krediti.

Brenda ndërfaqes së aplikacionit TacoTranslate, krijoni një projekt dhe navigoni te skeda e çelësave API. Krijoni një çelës read dhe një çelës read/write. Ne do t'i ruajmë si variabla mjedisore. Çelësi read është ai që e quajmë public dhe çelësi read/write është secret. Për shembull, mund t'i shtoni në një skedar .env në rrënjën e projektit tuaj.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Sigurohuni që kurrë të mos zbuloni çelësin sekret të API-së read/write në mjediset e prodhimit në anën e klientit.

Gjithashtu do të shtojmë edhe dy variabla të mjedisit: TACOTRANSLATE_DEFAULT_LOCALE dhe TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Kodi i lokalit të parazgjedhur (fallback). Në këtë shembull, do ta vendosim në en për anglishten.
• TACOTRANSLATE_ORIGIN: “Dosja” ku do të ruhen tekstet tuaja, si p.sh. URL‑ja e faqes suaj të internetit. Lexoni më shumë rreth origjinave këtu.

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

Hapi 3: Konfigurimi i TacoTranslate

Për të integruar TacoTranslate me aplikacionin tuaj, do t'ju duhet të krijoni një klient duke përdorur çelësat e API-së që keni krijuar më parë. Për shembull, krijoni një skedar me emrin /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;

Së shpejti do të përcaktojmë automatikisht TACOTRANSLATE_API_KEY dhe TACOTRANSLATE_PROJECT_LOCALE.

Krijimi i klientit në një skedar të veçantë e bën të lehtë përdorimin e tij më vonë. getLocales është thjesht një funksion ndihmës me disa mekanizma të integruar për trajtimin e gabimeve. Tani, krijoni një skedar të quajtur /app/[locale]/tacotranslate.tsx, ku do të implementojmë ofruesin 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>
	);
}

Vini re 'use client'; që tregon se ky është një komponent klienti.

Tani që ofruesi i kontekstit është gati, krijoni një skedar të quajtur /app/[locale]/layout.tsx, layout-i rrënjësor në aplikacionin tonë. Vini re se kjo rrugë përmban një dosje që përdor Dynamic Routes, ku [locale] është parametri dinamik.

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

Gjëja e parë që duhet të vini re këtu është se po përdorim parametrin tonë Dynamic Route [locale] për të marrë përkthimet për atë gjuhë. Për më tepër, generateStaticParams po siguron që të gjitha kodet e lokalit që i keni aktivizuar për projektin tuaj janë të gjeneruara paraprakisht.

Tani, le të ndërtojmë faqen tonë të parë! Krijoni një skedar të quajtur /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!" />
	);
}

Vini re variablën revalidate që i thotë Next.js të rindërtojë faqen pas 60 sekondash dhe t'i mbajë përkthimet tuaja të përditësuara.

Hapi 4: Zbatimi i renderizimit në anën e serverit

TacoTranslate mbështet renderimin në anën e serverit. Kjo përmirëson ndjeshëm përvojën e përdoruesit duke shfaqur menjëherë përmbajtjen e përkthyer, në vend që së pari të shfaqet për një çast përmbajtja e papërkthyer. Për më tepër, mund të shmangim kërkesat në rrjet nga ana e klientit, sepse tashmë kemi përkthimet që na nevojiten për faqen që po e shikon përdoruesi.

Për të vendosur renderizimin në anën e serverit, krijoni ose modifikoni /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};
};

Modifikoni kontrollin isProduction për t'iu përshtatur konfigurimit tuaj. Nëse true, TacoTranslate do të shfaqë çelësin publik të API-së. Nëse jemi në një mjedis lokal, test ose staging (isProduction is false), do të përdorim çelësin sekret read/write të API-së për të siguruar që vargjet e reja të dërgohen për përkthim.

Për të siguruar që rutimi dhe ridrejtimi të funksionojnë si duhet, do të duhet të krijojmë një skedar të quajtur /middleware.ts. Duke përdorur Middleware, mund t'i ridrejtojmë përdoruesit te faqet e paraqitura në gjuhën e tyre të preferuar.

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

Sigurohuni që të konfiguroni matcher në përputhje me dokumentacionin e Next.js Middleware.

Nga ana e klientit, mund të ndryshoni cookie-n locale për të ndryshuar gjuhën e preferuar të përdoruesit. Shihni kodin e plotë të shembullit për ide se si ta bëni këtë!

Hapi 5: Publikoni dhe testoni!

Kemi mbaruar! Aplikacioni juaj React tani do të përkthehet automatikisht kur të shtoni ndonjë varg në komponentin Translate. Vini re se vetëm mjediset me lejet read/write mbi çelësin e API-së do të mund të krijojnë vargje të reja për t'u përkthyer. Ne rekomandojmë të keni një mjedis staging të mbyllur dhe të sigurt ku mund ta testoni aplikacionin tuaj të produksionit me një çelës API të tillë, duke shtuar vargje të reja para se të shkoni live. Kjo do të parandalojë që dikush të vjedhë çelësin tuaj sekret të API-së dhe, potencialisht, të mbingarkojë projektin tuaj të përkthimit duke shtuar vargje të reja, të pa lidhura.

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!