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

Որքան աշխարհը դառնում է ավելի գլոբալացված, այնքան էլ ավելի կարևոր է, որ վեբ մշակողները ստեղծեն հավելվածներ, որոնք կարող են ծառայել տարբեր երկրներից և մշակույթներից օգտվողներին։ Դրա հասնելու ամենակարևոր եղանակներից մեկը միջազգայինացում (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-ի կարգավորումը

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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, մեր application's արմատային դասավորությունը: Նշեք, որ այս ճանապարհը ունի պանակ, որը օգտագործում է 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 կուքին՝ փոխելու օգտվողի նախընտրած լեզուն։ Խնդրում ենք դիտել ամբողջական օրինակ կոդը՝ իմանալու, թե ինչպես դա անել։

Հասարակաց 5: Վերբեռնեք և փորձեք!

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

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

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