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