Ինչպես իրականացնել միջազգայինացումը Next.js ծրագրում, որը օգտագործում է App Router

Երբ աշխարհը դարձել է ավելի գլոբալացված, վեբ ծրագրավորողների համար ավելի կարևոր է ստեղծել հավելվածներ, որոնք կարող են ծառայել տարբեր երկրների և մշակույթների օգտվողներին։ Այդ նպատակին հասնելու մի հիմնական ուղին միջազգայինացում (i18n) է, որը թույլ է տալիս ձեր հավելվածը հարմարվել տարբեր լեզուների, արժույթների և ամսաթվերի ձևաչափերի։

Այս հոդվածում մենք կքննարկենք, թե ինչպես ավելացնել միջազգայինացում ձեր React Next.js հավելվածում՝ օգտագործելով սերվերային հատվածի արտապատկերում: TL;DR: Այստեղ տեսեք լրիվ օրինակները։

Այս ուղեցույցը նախատեսված է Next.js ծրագրերի համար, որոնք օգտագործում են App Router:
Եթե օգտագործում եք Pages Router, դիտեք այս ուղեցույցը։

Քայլ 1: Տեղադրել i18n գրադարան

Ձեր Next.js հավելվածում բազմալեզվայնության իրականացման համար մենք սկզբում կընտրենք i18n գրադարան։ Կան մի քանի հանրաճանաչ գրադարաններ, այդ թվում next-intl, սակայն այս օրինակ میں մենք կօգտագործենք TacoTranslate։

TacoTranslate ավտոմատ կերպով թարգմանում է ձեր տողերը ցանկացած լեզվով՝ օգտագործելով առաջադեմ արհեստական բանականություն, և ազատում է ձեզ JSON ֆայլերի ձանձրալի կառավարման բեռից։

Պատրաստվեք այն տեղադրել npm–ով ձեր տերմինալում։

npm install tacotranslate

Քայլ 2՝ Ստեղծեք անվճար TacoTranslate հաշիվ

Հիմա, երբ մոդուլը տեղադրված է, ժամանակն է ստեղծելու ձեր TacoTranslate հաշիվը, թարգմանության նախագիծը և համապատասխան API բանալիները։ Ստեղծեք հաշիվ այստեղ։ Դա անվճար է և չի պահանջում կրեդիտ քարտի ավելացում։

TacoTranslate հավելվածի UI-ում ստեղծեք նախագիծ և անցեք դրա API բանալիների ներդիրին։ Ստեղծեք մեկ read բանալին և մեկ read/write բանալին։ Մենք դրանք կպահպանենք որպես շրջակա միջավայրի փոփոխականներ։ read բանալին այն է, ինչ մենք կոչում ենք public, իսկ read/write բանալին՝ secret: Օրինակ, դրանք կարող եք ավելացնել Ձեր նախագծի արմատային թղթապանակի .env ֆայլում։

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Համոզվեք, որ երբեք չթողնեք գաղտնի read/write API բանալին հաճախորդի կողմի արտադրական միջավայրերին:

Մենք նաև կավելացնենք երկու լրացուցիչ միջավայրի փոփոխականներ՝ TACOTRANSLATE_DEFAULT_LOCALE և TACOTRANSLATE_ORIGIN:

• TACOTRANSLATE_DEFAULT_LOCALE`՝ Նախնական պահելու տեղական կոդը։ Այս օրինակով, մենք այն սահմանելու ենք որպես en՝ անգլերենի համար։
• TACOTRANSLATE_ORIGIN`՝ «թղթապահ»՝ որտեղ ձեր տեքստերը կպահվեն, ինչպես, օրինակ, ձեր կայքի URL-ը։ Ավելի մանրամասն կարդացեք এখানে՝ σχετικά օրիենտացիաների մասին։

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

Քայլ 3. TacoTranslate-ի կարգավորում

ՏակոԹռանսլեյթը ինտեգրելու համար ձեր հավելվածի հետ, անհրաժեշտ է ստեղծել հաճախորդ՝ նախորդնոչ API բանալիների միջոցով։ Օրինակ, ստեղծեք ֆայլ՝ անվանված /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;

Մենք շուտով ավտոմատ կերպով սահմանելու ենք TACOTRANSLATE_API_KEY և TACOTRANSLATE_PROJECT_LOCALE:

Հաճախորդի ստեղծումը առանձին ֆայլում հեշտացնում է այն հետագայում կրկին օգտագործելը։ getLocales պարզապես օգտակար ֆունկցիա է, որը պարունակում է որոշ սարքավորված սխալների կառավարման մեխանիզմներ։ Հիմա ստեղծեք ֆայլ, որը կոչվում է /app/[locale]/tacotranslate.tsx, որտեղ մենք կիրականացնենք 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>
	);
}

Նշեք 'use client'; որը ցույց է տալիս, որ սա կլայենտի կոմպոնենտ է։

Հիմա, երբ կոնտեքստի պրովայդերը պատրաստ է, ստեղծեք ֆայլ՝ անվանված /app/[locale]/layout.tsx, որը մեր հավելվածի արմատային լեյաուտն է։ Ի նկատի ունեցեք, որ այս ուղին ունի պանակ, որը օգտագործում է Dynamic Routes, որտեղ [locale] դինամիկ պարամետր է։

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

Առաջին կարևորը այստեղ նշելն այն է, որ մենք օգտագործում ենք մեր Dynamic Route պարամետրը [locale]՝ այդ լեզվի համար թարգմանությունները ներբեռնելու համար։ Մեծապես նաև generateStaticParams ապահովում է, որ ձեր նախագծի համար ակտիվացված բոլոր տիրույթային կոդերը նախնական ձևով ստեղծվեն։

Հիմա ստեղծենք մեր առաջին էջը։ Ստեղծեք ֆայլ անունով /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!" />
	);
}

Ուշադրություն դարձրեք revalidate փոփոխականի վրա, որը հայտնի է Next.js-ին վերաբեռնել էջը 60 վայրկյան անց և պահել ձեր թարգմանումները թարմացված:

Քայլ 4․ Հեղինակային կողմի ռենդերինգի իրականացում

TacoTranslate-ն աջակցում է սերվերային կողմի վերակառուցմանը։ Սա իսքանչելիորեն բարելավում է օգտատերերի փորձը՝ անմիջապես ցուցադրելով թարգմանված բովանդակությունը, առանց նախքան դա անթարգման բովանդակության պատասխանատու մի պահակի։ Բացի այդ, մենք կարող ենք շրջանցել ցանցային հարցումները հաճախորդի կողմում, քանի որ արդեն ունենք օգտատերը դիտող էջի համար անհրաժեշտ թարգմանությունները։

Սերվերի կողմի մատուցումը կարգավորելու համար ստեղծեք կամ փոփոխեք /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};
};

Խմբագրեք isProduction ստուգումը ձեր կարգավորման համաձայն։ Եթե true, TacoTranslate-ը ցույց կտա հանրային API բանալին։ Եթե մենք տեղական, փորձարկման կամ նախշաբաղադրիչ միջավայրում ենք (isProduction is false), մենք կկիրառենք գաղտնի read/write API բանալին` համոզվելու համար, որ նոր տեքստերը ուղարկվում են թարգմանության։

Մասնագետ երթուղղումը և վերստուգումը աշխատելու համար, մեզ անհրաժեշտ կլինի ստեղծել ֆայլ՝ /middleware.ts: Օգտագործելով Middleware, մենք կարող ենք օգտագործողներին ուղարկել իրենց նախընտրած լեզվով ներկայացված էջերին:

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

Համոզվեք, որ matcher կարգավորվի համաձայն Next.js Middleware-ի փաստաթղթի։

Հաճախորդի կողմում դուք կարող եք փոփոխել locale cookie-ն՝ փոխելու համար, թե որն է օգտագործողի նախընտրած լեզուն: Խնդրում ենք դիտել ընդհանուր օրինակային կոդը՝ իմանալու, թե ինչպես դա անել:

Քայլ 5․ Տեղաբաշխեք և փորձարկեք։

Մենք ավարտել ենք: Ձեր React հավելվածը այժմ ավտոմատ կերպով կթարգմանվի, երբ դուք ավելացնեք ցանկացած տեքստ Translate կոմպոնենտում: Գրանցեք, որ միայն այն միջավայրերը, որոնցում read/write իրավունքներ կան API բանալու նկատմամբ, կարող են ստեղծել նոր տեքստեր թարգմանելու համար: Խնդրում ենք ունենալ փակ և ապահովված ստեյջինգ միջավայր, որտեղ կարող եք ստուգել ձեր պրոդուկցիոն հավելվածը նման API բանալիով՝ նախքան հրապարակումը նոր տեքստեր ավելացնելով: Սա կխոչընդոտի, որ որևէ մեկը գողանա ձեր գաղտնի API բանալին և հնարավորինս կխուսափի թարգմանական նախագիծը ավելորդ, փոխկապակցված olmayan տեքստերով ծանրաբեռնելուց:

Դուք կարող եք ստուգել ամբողջական օրինակները մեր GitHub պրոֆիլում։ Այնտեղ դուք կգտնեք նաև օրինակ, թե ինչպես անել սա օգտագործելով Pages Router։ Եթե որեւէ խնդիր ունենաք, ազատորեն հետադարձ կապ հաստատեք, և մենք ձեզ ուրախորեն կօգնենք։

TacoTranslate-ն թույլ է տալիս ձեզ ավտոմատ կերպով լոկալիզացնել ձեր React հավելվածները արագ և ցանկացած լեզվով։ Սկսեք այսօր!