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

Мына жерден біздің GitHub профиліміздегі толық мысалды қарауды ұмытпаңыз. Сондай-ақ, онда Pages Router қолданып қалай жасау керектігі туралы мысал таба аласыз! Кез келген мәселелер туындаса, бізге хабарласыңыз, біз сізге қуана көмек көрсетеміз.

TacoTranslate сіздің React қолданбаларыңызды кез келген тілге жылдам және автоматты түрде локализациялауға мүмкіндік береді. Бүгіннен бастап бастаңыз!