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

Ndërsa bota bëhet më globale, është gjithnjë e më e rëndësishme për zhvilluesit e faqeve të internetit të ndërtojnë aplikacione që mund t'u përgjigjen përdoruesve nga vende dhe kultura të ndryshme. Një nga mënyrat kryesore për të arritur këtë është përmes ndërkombëtarizimit (i18n), i cili ju lejon të përshtatni aplikacionin tuaj për gjuhë, monedha dhe formate datash të ndryshme.

Në këtë artikull, do të eksplorojmë se si të shtoni ndërkombëtarizimin në aplikacionin tuaj React Next.js, me renderim nga ana e serverit. TL;DR: Shikoni 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, shikoni këtë udhëzues në vend të tij.

Hapi 1: Instalo një bibliotekë i18n

Për të zbatuar internacionalizimin 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 stringjet tuaja në çdo gjuhë duke përdorur AI me teknologji të avancuar, dhe ju lirëson nga menaxhimi i lodhshëm i skedarëve JSON.

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

npm install tacotranslate

Hapi 2: Krijo një llogari falas në TacoTranslate

Tani që e keni instaluar modulin, është koha të krijoni llogarinë tuaj në 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 kartë krediti.

Brenda ndërfaqes së përdoruesit të aplikacionit TacoTranslate, krijoni një projekt dhe shkoni te skeda e çelësave API. Krijoni një çelës read dhe një çelës read/write. Ne do t’i ruajmë ato si ndryshore mjedisi. Çelësi read është ai që ne e quajmë public dhe çelësi read/write është secret. Për shembull, mund t’i shtoni ato 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 rrjedhni çelësin sekret read/write API në mjediset e prodhimit në anën e klientit.

Ne do të shtojmë edhe dy variabla të tjerë mjedisi: TACOTRANSLATE_DEFAULT_LOCALE dhe TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Kodi i lokalit të parazgjedhur të rezervës. Në këtë shembull, do ta vendosim në en për Anglisht.
• TACOTRANSLATE_ORIGIN: “Dosja” ku do të ruhen vargjet tuaja, si p.sh. URL-ja e faqes tuaj të internetit. Lexoni më shumë rreth origjinave këtu.

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

Hapi 3: Vendosja e TacoTranslate

Për të integruar TacoTranslate me aplikacionin tuaj, do t'ju duhet të krijoni një klient duke përdorur çelësa API nga 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;

Ne do të përcaktojmë automatikisht TACOTRANSLATE_API_KEY dhe TACOTRANSLATE_PROJECT_LOCALE së shpejti.

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 trajtime të gabimeve të integruara. Tani, krijo një skedar me emrin /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.

Me ofruesin e kontekstit tashmë gati për përdorim, krijo një skedar të quajtur /app/[locale]/layout.tsx, layout-in rrënjor në aplikacionin tonë. Vini re se kjo rrugë ka 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ë vërehet këtu është se po përdorim parametri tonë Dynamic Route [locale] për të marrë përkthimet për atë gjuhë. Përveç kësaj, generateStaticParams sigurohet që të gjitha kodet e lokalit që keni aktivizuar për projektin tuaj të jenë parapërpunuar.

Tani, le të ndërtojmë faqen tonë të parë! Krijoni një skedar me emrin /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 variablin revalidate që i thotë Next.js të rindërtojë faqen pas 60 sekondash, dhe të mbajë përkthimet tuaja të përditësuara.

Hapi 4: Zbatimi i rendering-ut nga ana e serverit

TacoTranslate mbështet renderimin në anën e serverit. Kjo përmirëson shumë përvojën e përdoruesit duke treguar menjëherë përmbajtjen e përkthyer, në vend të një shfaqjeje të shkurtër të përmbajtjes së papërkthyer më parë. Gjithashtu, mund të anashkalojmë kërkesat e rrjetit në klient, sepse ne tashmë kemi përkthimet që na duhen për faqen që po shikon përdoruesi.

Për të vendosur renderimin 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 e isProduction për t'iu përshtatur konfigurimit tuaj. Nëse true, TacoTranslate do të shfaqë çelësin publik API. Nëse jemi në një mjedis lokal, testimi ose inskenimi (isProduction is false), do të përdorim çelësin sekret read/write API për t'u siguruar që vargjet e reja të dërgohen për përkthim.

Për të siguruar që rutimi dhe ridrejtimi funksionojnë siç pritet, do të duhet të krijojmë një skedar të quajtur /middleware.ts. Duke përdorur Middleware, ne mund t'i ridrejtojmë përdoruesit në 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.

Në klient, ju mund të ndryshoni kukinë locale për të ndryshuar gjuhën e preferuar të përdoruesit. Ju lutem shikoni kodin e plotë të shembullit për ide se si ta bëni këtë!

Hapi 5: Vendoseni dhe testi!

Kemi mbaruar! Aplikacioni juaj React tani do të përkthehet automatikisht kur të shtoni ndonjë varg të ri në një komponent Translate. Vini re se vetëm mjediset me lejet read/write mbi çelësin API do të jenë në gjendje 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 të testoni aplikacionin tuaj në prodhim me një çelës API të tillë, duke shtuar vargje të reja para se të bëhet i disponueshëm për publikun. Kjo do të parandalojë këdo që të vjedhë çelësin tuaj sekret API dhe potencialisht të mbingarkojë projektin tuaj të përkthimit duke shtuar vargje të reja, të pështatshme.

Sigurohuni të hidhni një sy shembullit të plotë në profilin tonë në GitHub. Atje, do të gjeni gjithashtu një shembull se si të bëni këtë duke përdorur Pages Router![Nëse hasni ndonjë problem, mos hezitoni të na kontaktoni, dhe do të jemi më shumë se të lumtur t'ju ndihmojmë.

TacoTranslate ju lejon të lokalizoni automatikisht aplikacionet tuaja React shpejt në dhe nga çdo gjuhë. Filloni sot!