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 заманауи AI пайдаланып, сіздің жолдарыңызды кез келген тілге автоматты түрде аударады және 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 мекенжайы. Мұнда origin туралы көбірек оқыңыз.

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-қадам: Жариялап, тексеріңіз!

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

Міндетті түрде біздің GitHub профиліміздегі толық мысалды қарап шығыңыз. Сонда сіз сондай-ақ оны Pages Router пайдаланып қалай жасауға болатыны туралы мысалды таба аласыз! Егер қандай да бір қиындықтарға тап болсаңыз, байланысыңыз
TacoTranslate React қолданбаларыңызды кез келген тілге және кез келген тілден автоматты түрде тез локалдауға мүмкіндік береді. Бүгіннен бастаңыз!