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

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

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

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

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

Next.js қолданбаңызда халықаралықтандыруды (i18n) енгізу үшін алдымен 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 секундтан кейін бетті қайта құрауға және аудармаларыңызды өзекті ұстауға жауапты 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 кілтін көрсетеді. Егер біз жергілікті, тестілік немесе 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 рұқсаты бар орта ғана аударылатын жаңа мәтіндерді жасай алады. Біз өндірістік қолданбаңызды тіріге шығармай тұрып жаңа мәтіндер қосып тестілеу үшін жабық және қорғалған 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!