როგორ დავნერგოთ ინტერნაციონალიზაცია Next.js აპლიკაციაში, რომელიც იყენებს App Router

მსოფლიოს გლობალიზაციის ზრდასთან ერთად, სულ უფრო მნიშვნელოვანი ხდება, რომ ვებ-დეველოპერებმა შექმნან აპლიკაციები, რომლებიც მოემსახურებიან სხვადასხვა ქვეყნებისა და კულტურების მომხმარებლებს. ერთ-ერთი მთავარი გზა ამის მისაღწევად არის საერთაშორისოინტერნაციონალიზაცია (i18n), რომელიც საშუალებას გაძლევთ დააადაპტიროთ თქვენი აპლიკაცია სხვადასხვა ენებისთვის, ვალუტებისთვის და თარიღის ფორმატებისთვის.

ამ სტატიაში გავარკვევთ, როგორ დაამატოთ საერთაშორისო ინტერნაციონალიზაცია თქვენს React Next.js აპლიკაციას სერვერული მხარის რენდერინგის გამოყენებით. TL;DR: სრული მაგალითი იხილეთ აქ.

ეს გზამკვლევი განკუთვნილია Next.js აპლიკაციებისთვის, რომლებიც იყენებენ App Router.
თუ იყენებთ 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 გასაღები. ჩვენ მათ შევინახავთ როგორც გარემოს ცვლადებს. 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: ნაგულისხმევი რეზერვული (fallback) ლოკალის კოდი. ამ მაგალითში ვაყენებთ მას 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!" />
	);
}

გაითვალისწინეთ revalidate ცვლადი, რომელიც უბრძანებს Next.js-ს გვერდი 60 წამში ერთხელ ხელახლა ააგოს და შეინარჩუნებს თქვენს თარგმანებს განახლებულ მდგომარეობაში.

ნაბიჯი 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 კუკი, რათა შეცვალოთ მომხმარებლის სასურველი ენა. იხილეთ სრული მაგალითის კოდი, იმისათვის რომ ნახოთ, როგორ უნდა გაკეთდეს ეს!

ნაბიჯი 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!