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

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

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

ეს სახელმძღვანელო განკუთვნილია Next.js აპლიკაციებისთვის, რომლებიც იყენებენ App Router.
თუ იყენებთ Pages Router, ამის ნაცვლად იხილეთ ეს სახელმძღვანელო.

ნაბიჯი 1: დააინსტალირეთ i18n ბიბლიოთეკა

ინტერნაციონალიზაციის (i18n) თქვენი Next.js აპლიკაციაში დანერგვისათვის, პირველ რიგში ავირჩევთ i18n ბიბლიოთეკას. არსებობს რამდენიმე პოპულარული ბიბლიოთეკა, მათ შორის next-intl. ამ მაგალითში კი ჩვენ გამოვიყენებთ TacoTranslate.

TacoTranslate თანამედროვე AI-ის გამოყენებით ავტომატურად თარგმნის თქვენს სტრინგებს ნებისმიერ ენაზე და მოგაშორებთ JSON ფაილების მოსაწყენ მართვას.

დავაინსტალიროთ იგი ტერმინალში გამოყენებით npm:

npm install tacotranslate

ნაბიჯი 2: შექმენით უფასო TacoTranslate ანგარიში

ახლა, როდესაც მოდული დაინსტალირებული გაქვთ, დროა შექმნათ თქვენი TacoTranslate ანგარიში, თარგმნის პროექტი და შესაბამისი API გასაღებები. შექმენით ანგარიში აქ. ეს უფასოა და საკრედიტო ბარათის დამატება არ არის საჭირო.

TacoTranslate-ის აპლიკაციის UI-ში შექმენით პროექტი და გადადით მისი API კლავიშების ჩანართზე. შექმენით ერთი read გასაღები და ერთი read/write გასაღები. ჩვენ მათ შევინახავთ გარემოს ცვლადებად. read გასაღები არის ის, რასაც ვუწოდებთ public, ხოლო read/write გასაღები არის secret. მაგალითად, შეგიძლიათ დაამატოთ ისინი თქვენი პროექტის ძირითადი (root) დირექტორიაში არსებულ .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 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!