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

ახლა, შექმნათ ჩვენი პირველი გვერდი! შექმენით ფაილი სახელად /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!