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

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

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

ეს სახელმძღვანელო განკუთვნილია Next.js აპლიკაციებისთვის, რომლებიც იყენებენ App Router.
თუ იყენებთ Pages 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: ნაგულისხმევი რეზერვული ლოკალის კოდი. ამ მაგალითში მას დავადგენთ როგორც 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 cookie, რათა შეცვალოთ მომხმარებლის სასურველი ენა. გთხოვთ, იხილეთ სრული მაგალითის კოდი, რათა მიიღოთ იდეები, თუ როგორ უნდა გააკეთოთ ეს!

ნაბიჯი 5: გამოაქვეყნეთ და შეამოწმეთ!

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

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!