App Router-ді пайдаланатын Next.js қосымшасында интернационализацияны (i18n) қалай жүзеге асыруға болады

Әлем жаһанданған сайын, веб-әзірлеушілер үшін әртүрлі елдер мен мәдениеттерден келген пайдаланушыларға ыңғайлы қосымшалар жасау маңыздырақ болып келеді. Бұған қол жеткізудің негізгі тәсілдерінің бірі — интернационализация (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!" />
	);
}

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 кілтін көрсетеді. Егер біз жергілікті, тестілеу немесе 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!