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 ең озық ЖИ көмегімен сіздің жолдарыңызды кез келген тілге автоматты түрде аударады және 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-адресі. Осы жерде origins туралы толығырақ оқыңыз.

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

Ескеріңіз 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 кілтіңізді ұрланудан қорғайды және аударма жобасының көлемін қажетсіз, байланыссыз мәтіндермен көбейіп кетуінен сақтайды.

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!