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

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

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

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

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

თქვენი Next.js აპლიკაციაში საერთაშორისო მხარდაჭერის (internationalization) განხორციელებისთვის, პირველ რიგში ამოვირჩიოთ 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: სტანდარტული საყრდენი ლოკალ კოდი. ამ მაგალითში, ვაყენებთ 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 უჭერს მხარს სერვერზე გვერდის რენდერingu. ეს მნიშვნელოვნად აუმჯობესებს მომხმარებლის გამოცდილებას, გამოაქვეყნებს თარგმნილ მასალას დაუყოვნებლივ, untranslated მასალის კაშკაშის ნაცვლად. დამატებით, ჩვენ შეგვიძლია გამოვტოვოთ ქსელური მოთხოვნები კლიენტზე, რადგან ჩვენ უკვე გვაქვს თარგმნები იმ გვერდისთვის, რომელსაც მომხმარებელი უყურებს.

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

წყópი 5: განაახლეთ და შეამოწმეთ!

ჩვენ დასრულებულია! თქვენი React აპლიკაცია ახლა ავტომატურად გადაითარგმნება, როდესაც დაამატებთ ნებისმიერ სტრიქონს Translate კომპონენტში. გაითვალისწინეთ, რომ მხოლოდ ის გარემოებები, სადაც API გასაღებს აქვს read/write დაზუსტება, შეძლებენ ახალი სტრიქონების შექმნას თარგმნისთვის. ჩვენ ვურჩევთ ჰქონდეთ დახურული და დაცული სტეიჯინგ გარემო, სადაც შეძლებთ თქვენი პროდაქშენის აპლიკაციის ტესტირებას ამგვარი API გასაღებით, დაამატოთ ახალი სტრიქონები სანამ აპლიკაცია პირდაპირ ეთერში გავა. ეს დაგიცავთ თქვენი საიდუმლო API გასაღების ჩასაკუთრებისგან და შეამცირებს თქვენი თარგმნის პროექტის გადატვირთვის შესაძლებლობას, უადგილო და სხვადასხვა სტრიქონების დამატებით.

დარწმუნდით, რომ დაათვალიერეთ სრული მაგალითი ჩვენს GitHub პროფილზე. იქ ასევე ნახავთ მაგალითს, თუ როგორ უნდა გააკეთოთ ეს გამოყენების დროს Pages Router -ს! თუ რაიმე პრობლემა შეგხვდებათ, თავისუფლად მოგვმართეთ, და ჩვენ სიამოვნებით დაგეხმარებით.

TacoTranslate საშუალებას გაძლევთ ავტომატურად ლოკალიზება გაუკეთოთ თქვენს React აპლიკაციებს სწრაფად ნებისმიერი ენის მიმართულებით. დაიწყეთ დღესვე!