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

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

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

.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. წყაროების შესახებ მეტი წაიკითხეთ აქ.

.env

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

3-ე ნაბიჯი: TacoTranslate-ის კონფიგურაცია

TacoTranslate-ის თქვენი აპლიკაციაში ინტეგრირებისთვის, თქვენ დაგჭირდებათ კლიენტის შექმნა, რომელიც გამოიყენებს ზემოთ მითითებულ API გასაღებებებს. მაგალითისთვის, შექმენით ფაილი სახელით /tacotranslate-client.js.

/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 პროვაიდერს.

/app/[locale]/tacotranslate.tsx

'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] არის დინამიკური პარამეტრი.

/app/[locale]/layout.tsx

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.

/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:

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

/middleware.ts

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