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 соңғы заманғы AI технологиясын пайдаланып, сіздің мәтіндеріңізді кез келген тілге автоматты түрде аударады және 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-мекенжайы. Орыс жайлы мұнда көбірек оқыңыз.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

3-қадам: TacoTranslate орнату

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 сервер жағындағы рендерлеуді қолдайды. Бұл пайдаланушы тәжірибесін едәуір жақсартады, себебі аударылған мазмұнды дереу көрсетеді, бірінші болып аударылмаған мазмұнның жыпылықтауын болдырмайды. Сонымен қатар, біз клиент жағында желі сұрауларынан бас тарта аламыз, өйткені пайдаланушы көріп отырған бет үшін қажетті аудармаларымыз бұрыннан бар.

Серверлік жағын көрсету (server side rendering) орнату үшін, /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 компонентіне кез келген жолды қосқан кезде автоматты түрде аударылатын болады. Назар аударыңыз, API кілтіне read/write рұқсаты бар орталар ғана аударылатын жаңа жолдарды жасай алады. Біз өндірістік қолданбаңызды сондай API кілтімен тестілеуге болатын жабық және қауіпсіз сценалық ортаны ұсынуды ұсынамыз, осылайша жаңа жолдарды орналастыру алдында қосуға болады. Бұл сіздің құпия API кілтіңіздің ұрлануына жол бермейді және аударма жобаңызды жаңа, байланыссыз жолдармен толтыру қаупін азайтады.

Міндетті түрде GitHub профиліміздегі толық мысалға көз жүгіртіңіз. Онда сіз бұл жұмысты Pages Router арқылы қалай орындауға болатынының мысалын да таба аласыз! Егер қандай да бір мәселеге тап болсаңыз, бізге хабарласыңыз
TacoTranslate сізге React қосымшаларыңызды кез келген тілге жылдам автоматты түрде аударуға мүмкіндік береді. Бүгіннен бастаңыз!