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-мекенжайы. 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!" />
	);
}

Бетті 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 қоғамдық 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);
}

Next.js Middleware құжаттамасына сәйкес matcher параметрін орнатқаныңызға көз жеткізіңіз.

Клиентте пайдаланушының қалаған тілін өзгерту үшін locale cookie файлын өзгерте аласыз. Қалай істеуге болатыны туралы идея алу үшін толық мысал кодын қараңыз!

Қадам 5: Жариялап, тексеріңіз!

Біз аяқтадық! Енді сіз Translate компонентіне кез келген жолдарды қосқанда сіздің React қосымшаңыз автоматты түрде аударылады. Назар аударыңыз: API кілтіндегі read/write рұқсаты бар орта ғана аударуға арналған жаңа жолдарды жасай алады. Біз өндірістік қосымшаны осындай 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!