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

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

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

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

გადადგმი ნაბიჯი 1: დააინსტალირეთ 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. მაგალითად, შეგიძლიათ დაამატოთ ისინი თქვენს პროექტის ფესვის საქაღალდეში არსებული .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 zorgt ervoor dat alle taalcodes die u voor uw project hebt geactiveerd, worden voorgeladen.

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