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

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

ამ სტატიაში დეტალურად განვიხილავთ, როგორ დაამატოთ საერთაშორისოატიზაცია თქვენს React Next.js აპლიკაციას, სერვერული ნაწილის რენდერინგით. TL;DR: ნახეთ სრული მაგალითი აქ.

ეს სახელმძღვანელო განკუთვნილია Next.js აპლიკაციებისთვის, რომლებიც იყენებენ App Router-ს.
თუ იყენებთ Pages Router-ს, ნახეთ ეს სახელმძღვანელო.

ნაბიჯი 1: დააინსტალირეთ i18n ბიბლიოთეკა

თქვენი Next.js აპლიკაციაში საერთაშორისო სტანდარტების იმპლემენტაციისთვის, პირველ რიგში, აირჩევთ i18n ბიბლიოთეკას. არსებობს რამდენიმე პოპულარული ბიბლიოთეკა, მათ შორის next-intl. ამ მაგალითში კი, ჩვენ გამოვიყენებთ TacoTranslate.

TacoTranslate გ automatische თარგმნის თქვენს სტრიქონებს ნებისმიერ ენაზე თანამედროვე 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 საკვანძის მოპარვასა და პოტენციურად თარგმანის প্রকეტში დაუკავშირებელი, არასაჭირო ტექსტების დამატებას.

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

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