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

დავაყენოთ ის თქვენს ტერმინალში, გამოიყენეთ npm:

npm install tacotranslate

ნაბიჯი 2: შექმენით უფასო TacoTranslate ანგარიში

ახლა, როცა მოდული უკვე დაინსტალირებული გაქვთ, დროა შექმნათ TacoTranslate ანგარიში, თარგმნის პროექტი და შესაბამისი API გასაღებები. შექმენით ანგარიში აქ. ეს უფასოა და არ მოითხოვს საკრედიტო ბარათის დამატებას.

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

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

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

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