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

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. დაწვრილებით გაეცანით origin-ების შესახებ აქ.

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