Next.js қолданбасында App Router пайдаланғанда халықаралықтауды қалай жүзеге асыру керек

Әлем жаһандану үдерісінде тереңірек енген сайын, веб-әзірлеушілерге әртүрлі елдер мен мәдениеттерден келген пайдаланушыларға лайықталған қолданбаларды жасау өте маңызды болуда. Мұны жүзеге асырудың негізгі тәсілдерінің бірі — халықаралықтандыру (i18n), ол сіздің қолданбаңызды әртүрлі тілдерге, валюталарға және күн форматтарына бейімдеуге мүмкіндік береді.

Бұл мақалада біз React Next.js қолданбаңызға сервер жағында рендерлеумен бірге халықаралықтандыруды қалай қосуға болатынын қарастырамыз. TL;DR: Толық мысалды осында қараңыз.

Бұл нұсқаулық App Router қолданатын Next.js қосымшаларына арналған.
Егер сіз Pages Router қолдансаңыз, оның орнына осы нұсқаулықты қараңыз.

1-қадам: i18n кітапханасын орнатыңыз

Next.js қосымшаңызда халықаралықтандыруды жүзеге асыру үшін алдымен i18n кітапханасын таңдаймыз. Бірнеше танымал кітапханалар бар, олардың ішінде next-intl бар. Алайда, осы мысалда біз TacoTranslate қолданамыз.

TacoTranslate сіздің жолдарınızı кез келген тілге автоматты түрде соңғы үлгідегі ИИ арқылы аударады және JSON файлдарын қажытып басқарудан босатады.

Оны терминалыңызда npm арқылы орнатайық:

npm install tacotranslate

2-қадам: Тегін TacoTranslate аккаунтын жасаңыз

Енді сіз модульді орнатқан соң, TacoTranslate аккаунтын, аударма жобасын және байланысты API кілттерін жасаудың уақыты келді. Мұнда аккаунт жасаңыз. Бұл тегін, және несие картасын қосуды талап етпейді.

TacoTranslate қолданба интерфейсінде жоба құрыңыз да, оның 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 құралын баптау

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!" />
	);
}

Next.js-ке бетті 60 секундтан кейін қайта құруды және аудармаларыңызды жаңартып отыруды хабарлайтын revalidate айнымалысына назар аударыңыз.

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-қадам: Жүктеу және сынау!

Біз аяқтадық! Енді сіз кез келген жолды Translate компонентіне қосқанда, сіздің React қолданбаңыз автоматты түрде аударылатын болады. Назар аударыңыз, тек read/write құқықтары бар API кілті бар ортада ғана аударуға арналған жаңа жолдарды жасауға болады. Біз сіздің өндірістік қолданбаңызды осындай API кілтімен жабық және қауіпсіз тестілеу ортасында сынап көруді ұсынамыз, және сол жерде белсендіру алдында жаңа жолдарды қосуға болады. Бұл сіздің құпия API кілтіңізді ұрлау және аударма жобаңызды мағынасыз, байланыспаған жаңа жолдармен толтырудан сақтайды.

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!