როგორ დავნერგოთ ინტერნაციონალიზაცია (i18n) Next.js აპლიკაციაში, რომელიც იყენებს Pages Router

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

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

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

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

ინტერნაციონალიზაციის (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: ნაგულისხმევი ჩანაცვლებითი (fallback) ლოკალის კოდი. ამ მაგალითში ვაყენებთ მას en-ად — ინგლისურისთვის.
• TACOTRANSLATE_ORIGIN: „ფოლდერი“, სადაც შენახული იქნება თქვენი ტექსტები, მაგალითად თქვენი ვებსაიტის URL. დეტალურად წაიკითხეთ origins-ის შესახებ აქ.

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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

მალე ავტომატურად დავაყენებთ TACOTRANSLATE_API_KEY.

კლიენტის ცალკე ფაილში შექმნა მოგვიანებით მის ხელახლა გამოყენებას აადვილებს. ახლა, მორგებული /pages/_app.tsx ფაილის გამოყენებით დავამატებთ TacoTranslate პროვაიდერს.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

თუ თქვენ უკვე გაქვთ მორგებული pageProps და _app.tsx, გთხოვთ გაფართოვოთ განსაზღვრება ზემოთ მოცემული თვისებებითა და კოდით.

Step 4: სერვერული მხარის რენდერინგის განხორციელება

TacoTranslate უზრუნველყოფს თქვენი თარგმნების სერვერულ რენდერირებას. ეს მნიშვნელოვნად აუმჯობესებს მომხმარებლის გამოცდილებას, რადგან თარგმნილი კონტენტი დაუყოვნებლივ ჩანს და თავდაპირველად არ ჩანს დაუთარგმნელი შინაარსი. გარდა ამისა, კლიენტზე შეგვიძლია გამოვტოვოთ ქსელური მოთხოვნები, რადგან უკვე გვაქვს ყველა საჭირო თარგმანი.

პირველ რიგში შევქმნით ან შევცვლით /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

დაარეგულირეთ isProduction შემოწმება თქვენი კონფიგურაციის შესაბამისად. თუ true, TacoTranslate გამოაჩენს საჯარო API გასაღებებს. თუ ვართ ადგილობრივ, ტესტურ ან სტეიჯინგ გარემოში (isProduction is false), გამოვიყენებთ საიდუმლო read/write API გასაღებს იმისთვის, რომ ახალი სტრიქონები გაიგზავნონ თარგმნისთვის.

ამ დრომდე ჩვენ Next.js აპლიკაცია დავაყენეთ მხოლოდ მხარდაჭერილი ენების სიით. შემდეგი, რასაც გავაკეთებთ, არის ყველა გვერდისთვის თარგმანების მიღება. ამისათვის თქვენს მოთხოვნებზე დაყრდნობით გამოიყენებთ ან getTacoTranslateStaticProps ან getTacoTranslateServerSideProps.

ეს ფუნქციები იღებენ სამ არგუმენტს: ერთი Next.js Static Props Context ობიექტი, TacoTranslate-ის კონფიგურაცია და არასავალდებულო Next.js თვისებები. გაითვალისწინეთ, რომ revalidate პარამეტრი getTacoTranslateStaticProps–ში ნაგულისხმევად არის დაყენებული 60, რათა თქვენი თარგმანები აქტუალური დარჩეს.

ეს ფუნქციებიდან ნებისმიერი გვერდზე გამოსაყენებლად, ვივარაუდოთ რომ გაქვთ გვერდის ფაილი, როგორიცაა /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

ახლა უკვე შეგიძლიათ გამოიყენოთ Translate კომპონენტი, რათა თარგმნოთ სტრინგები თქვენს ყველა React კომპონენტში.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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

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

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

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