როგორ დავნერგოთ საერთაშორისო სტანდარტები 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. მაგალითად, შეგიძლიათ დაამატოთ ისინი თქვენს პროექტის root დირექტორიაში მდებარე .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 მხარს უჭერს სერვერზე გვერდის გამოტანას. ეს მნიშვნელოვნად აუმჯობესებს მომხმარებლის გამოცდილებას, რადგან თარგმნილი კონტენტი მალევე მთავრდება, პირველ რიგში არაა ნაჩვენები თარგმნილის გარეშე კონტენტის მაკემი. დამატებით, შესაძლებელია ქსელური მოთხოვნების გამოტოვება კლიენტზე, რადგან უკვე გვაქვს თარგმანები, რომლებიც გვჭირდება მომხმარებლის მიერ ნანახი გვერდისთვის.

სერვერზე მხარის რენდერინგის დასაწყებად შექმენით ან შეცვალეთ /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!