Si të implementoni internacionalizimin 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 që 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 ta arritur këtë është përmes internacionalizimit (i18n), i cili ju lejon të përshtatni aplikacionin tuaj me gjuhë, monedha dhe formate datash të ndryshme.

Në këtë artikull, do të eksplorojmë se si të shtoni internacionalizimin në aplikacionin tuaj React Next.js, me renderim 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, shikoni 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. Në këtë shembull, megjithatë, do të përdorim TacoTranslate.

TacoTranslate përkthe automatikisht vargjet tuaja në çdo gjuhë duke përdorur AI të avancuar, dhe ju lirëson nga menaxhimi i lodhshëm i skedarëve JSON.

Le ta instalojmë me 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 TacoTranslate, një projekt përkthimi dhe çelësat përkatës API. Krijoni një llogari këtu. Është falas, dhe nuk kërkon të shtoni kartë krediti.

Brenda ndërfaqes së aplikacionit TacoTranslate, krijo një projekt dhe navigo në skedën e çelësave API. Krijo një çelës read dhe një çelës read/write. Ne do t’i ruajmë ata si variabla mjedisore. Çelësi read është ai që quajmë public dhe çelësi read/write është secret. Për shembull, mund t’i shtosh ata në një skedar .env në rrënjën e projektit tënd.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

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

• TACOTRANSLATE_DEFAULT_LOCALE: Kodi i lokalizimit parazgjedhje për kthim. Në këtë shembull, do ta vendosim në en për anglisht.
• TACOTRANSLATE_ORIGIN: “Dosja” ku do të ruhen vargjet tuaja, si për shembull 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: Konfigurimi i TacoTranslate

Për të integruar TacoTranslate me aplikacionin tuaj, do t’ju duhet të krijoni një klient duke përdorur çelësat 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ë file të veçantë e bën të lehtë përdorimin e tij përsëri më vonë. getLocales është thjesht një funksion ndihmës me disa trajtime gabimesh të integruara. Tani, krijo një file me emrin /app/[locale]/tacotranslate.tsx, ku do të implementojmë TacoTranslate provider-in.

'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ërat e para që duhet të vini re këtu janë se po përdorim parametrin tonë Dynamic Route [locale] për të marrë përkthimet për atë gjuhë. Gjithashtu, generateStaticParams siguron që të gjitha kodet e lokaliteteve që keni aktivizuar për projektin tuaj të gjenerohen paraprakisht.

Tani, le të ndërtojmë faqen tonë të parë! Krijo 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 variablën 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 renderimit në anën e serverit

TacoTranslate mbështet renderimin nga ana e serverit. Kjo përmirëson ndjeshëm 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. Për më tepër, ne mund të shmangim kërkesat në rrjet në klient, sepse tashmë kemi përkthimet që na duhen për faqen që po shikon përdoruesi.

Për të vendosur server side rendering, 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};
};

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

Për të siguruar që routing dhe ridrejtimi të funksionojnë siç pritet, do të duhet të krijojmë një skedar me emrin /middleware.ts. Duke përdorur Middleware, mund të 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);
}

Sigurohu të konfigurosh matcher në përputhje me dokumentacionin e Next.js Middleware.

Në klient, ju mund të ndryshoni cookie-n locale për të ndryshuar se cila është gjuha e preferuar e përdoruesit. Ju lutemi shikoni kodin e plotë shembull për ide se si të bëni këtë!

Hapi 5: Bëj deploy dhe testo!

Kemi përfunduar! Aplikacioni juaj React tani do të përkthehet automatikisht kur të shtoni çfarëdo vargjesh në një komponent Translate. Vini re se vetëm ambientet me leje read/write mbi çelësin API do të kenë mundësi të krijojnë vargje të reja për t’u përkthyer. Ne rekomandojmë të keni një ambient staging të mbyllur dhe të sigurt ku të mund të testoni aplikacionin tuaj prodhues me një çelës API të tillë, duke shtuar vargje të reja para se të publikoni në mënyrë zyrtare. Kjo do të parandalojë që kushdo të vjedhë çelësin tuaj sekret API, dhe potencialisht të mbingarkojë projektin tuaj të përkthimit duke shtuar vargje të reja, të pasakta dhe 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!