App Router ашиглаж байгаа Next.js аппликейшинд олон улсынчлалыг (i18n) хэрхэн хэрэгжүүлэх вэ

Дэлхий улам бүр глобалшиж буй энэ үед вэб хөгжүүлэгчдэд янз бүрийн улс орон, соёлоос ирсэн хэрэглэгчдэд зориулсан програмуудыг бий болгох нь улам бүр чухал болж байна. Нэг гол арга нь олон хэлний дэмжлэг (internationalization, 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 програмын UI-д төсөл үүсгээд, API түлхүүрүүдийн таб руу орно. Нэг read түлхүүр болон нэг read/write түлхүүр үүсгэнэ. Бид эдгээрийг орчны хувьсагчид (environment variables) болгон хадгална. 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'; тэмдэглэгээнд анхаарна уу.

Context provider одоо бэлэн болсноор, аппликейшны үндсэн layout файлыг /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 түлхүүрийг ашиглана.

Чиглүүлэлт (routing) болон чиглүүлэлтийн (redirection) хүссэнээр ажиллахыг баталгаажуулахын тулд /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-р алхам: Байршуулж, туршина уу!

Бэлэн боллоо! Таны React аппликейшн одооноос эхлэн Translate компонентэд ямар нэгэн текст нэмэх бүрт автоматаар орчуулагдах болно. Анхаарна уу: 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!