როგორ დავნერგოთ ინტერნაციონალიზაცია 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 ავტომატურად თარგმნის თქვენს სტრინგებს ნებისმიერ ენაზე უახლესი AI ტექნოლოგიების გამოყენებით და მოგაშორებთ JSON ფაილების მოსაწყენ მართვას.

დავაინსტალიროთ იგი თქვენს ტერმინალში, npm–ის საშუალებით:

npm install tacotranslate

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

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

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 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!