App Router-ды пайдаланатын Next.js қолданбасында интернационализацияны (i18n) қалай іске асыруға болады 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 қолданбасының интерфейсінде жоба жасаңыз және оның 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!" />
	);
}

60 секунд өткеннен кейін Next.js бетті қайта құруды және аудармаларыңызды өзекті күйде ұстауды қамтамасыз ететін 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 қоғамдық (public) API кілтін көрсетеді. Егер біз жергілікті, тестілік немесе staging ортасында болсақ (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 қосымшаңыз автоматты түрде аударылады. Ескерту: тек API кілтінде read/write рұқсаты бар орта ғана аударылатын жаңа жолдарды құра алады. Біз өндіріске енгізбес бұрын осындай API кілтімен өндірістік қосымшаңызды сынап көруге арналған жабық және қорғалған staging ортасын ұстауды ұсынамыз. Бұл сіздің құпия 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!