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

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

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

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

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

თქვენი Next.js აპლიკაციისთვის ინტერნაციონალიზაციის (i18n) იმპლემენტაციისათვის, პირველ რიგში შევარჩევთ 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. მაგალითად, შეგიძლიათ დაამატოთ ისინი თქვენს პროექტის ფესვში არსებულ .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. მეტი ინფორმაცია ორიგინების შესახებ.

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

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

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