როგორ შევასრულოთ ინტერნაციონალიზაცია 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-ის დაყენება

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 მხარს უჭერს სერვერის მხარის რენდერингს. ეს მნიშვნელოვნად აუმჯობესებს მომხმარებლის გამოცდილებას, რადგან მთარგმნელობითი პროდუქტი გვიჩვენებს დაუყოვნებლივ, 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 ქუქი, რათა შეცვალოთ რა ენა ეძახება მომხმარებლისთვის პრეფერენცულად. გთხოვთ, იხილოთ სრული მაგალითის კოდი, რათა მიიღოთ იდეები თუ როგორ შეიძლება ეს გაკეთდეს!

ნაბიჯი 5: განათავსეთ და შეამოწმეთ!

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

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

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