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 мекенжайы. Түпнұсқалар туралы осында оқыңыз.

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