چگونه بین‌المللی‌سازی را در یک برنامه Next.js که از Pages Router استفاده می‌کند پیاده‌سازی کنیم

برنامهٔ React خود را با بین‌المللی‌سازی (i18n) قابل دسترسی‌تر کرده و به بازارهای جدید دست یابید.

با جهانی‌تر شدن جهان، برای توسعه‌دهندگان وب هر روز اهمیت بیشتری دارد که برنامه‌هایی بسازند که بتوانند به کاربران از کشورهای و فرهنگ‌های مختلف خدمت‌رسانی کنند. یکی از راه‌های کلیدی برای رسیدن به این هدف، بین‌المللی‌سازی (i18n) است که به شما اجازه می‌دهد برنامه‌تان را با زبان‌ها، ارزها و فرمت‌های تاریخ مختلف سازگار کنید.

در این آموزش، ما بررسی خواهیم کرد چگونه بین‌المللی‌سازی را به برنامه React Next.js خود اضافه کنیم، همراه با رندر سمت سرور. TL;DR: مثال کامل را اینجا ببینید.

این راهنما برای برنامه‌های Next.js است که از Pages Router استفاده می‌کنند.
اگر از App Router استفاده می‌کنید، لطفاً به این راهنما مراجعه کنید.

گام ۱: یک کتابخانه i18n را نصب کنید

برای پیاده‌سازی بین‌المللی‌سازی در برنامه Next.js خود، ابتدا یک کتابخانه i18n را انتخاب می‌کنیم. چندین کتابخانهٔ محبوب وجود دارد، از جمله next-intl. با این حال، در این مثال، ما از TacoTranslate استفاده خواهیم کرد.

TacoTranslate به‌طور خودکار رشته‌های شما را با استفاده از هوش مصنوعی پیشرفته به هر زبانی ترجمه می‌کند و شما را از مدیریت وقت‌گیر فایل‌های JSON رها می‌سازد.

بیایید آن را با استفاده از npm در ترمینال خود نصب کنیم:

npm install tacotranslate

مرحله ۲: یک حساب رایگان TacoTranslate ایجاد کنید

حالا که ماژول را نصب کرده‌اید، وقت آن است که حساب TacoTranslate خود، یک پروژه ترجمه و کلیدهای API مرتبط را ایجاد کنید. اینجا یک حساب بسازید. این رایگان است و نیازی به افزودن کارت اعتباری ندارد.

در رابط کاربری برنامهٔ TacoTranslate، یک پروژه ایجاد کنید و به زبانهٔ کلیدهای API آن بروید. یک کلید read و یک کلید read/write ایجاد کنید. ما آنها را به‌عنوان متغیرهای محیطی ذخیره خواهیم کرد. کلید read چیزی است که ما آن را public می‌نامیم، و کلید read/write همان secret است. برای مثال، می‌توانید آنها را در فایل .env در ریشهٔ پروژهٔ خود قرار دهید.

.env

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

اطمینان حاصل کنید که هرگز کلید API محرمانه read/write را در محیط‌های تولید سمت مشتری فاش نکنید.

ما همچنین دو متغیر محیطی دیگر نیز اضافه خواهیم کرد: TACOTRANSLATE_DEFAULT_LOCALE و TACOTRANSLATE_ORIGIN.

TACOTRANSLATE_DEFAULT_LOCALE: کد لوکال پیش‌فرض که به‌عنوان مقدار پشتیبان استفاده می‌شود. در این مثال آن را روی en برای انگلیسی تنظیم می‌کنیم.
TACOTRANSLATE_ORIGIN: «پوشه‌ای» که رشته‌های شما در آن ذخیره خواهند شد، مانند آدرس وب‌سایت شما. برای اطلاعات بیشتر دربارهٔ مبداها اینجا را بخوانید.

.env

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

گام ۳: راه‌اندازی TacoTranslate

برای یکپارچه‌سازی TacoTranslate با برنامهٔ خود، باید با استفاده از کلیدهای API که قبلاً ساختید یک کلاینت ایجاد کنید. برای مثال، فایلی به نام /tacotranslate-client.js ایجاد کنید.

/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 را اضافه خواهیم کرد.

/pages/_app.tsx

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 شروع خواهیم کرد.

/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) باشیم، از کلید API محرمانه read/write استفاده خواهیم کرد تا مطمئن شویم رشته‌های جدید برای ترجمه ارسال می‌شوند.

تا کنون تنها برنامهٔ Next.js را با فهرستی از زبان‌های پشتیبانی‌شده تنظیم کرده‌ایم. قدم بعدی این است که ترجمه‌ها را برای همهٔ صفحات شما دریافت کنیم. برای این کار، بسته به نیازهای خود از getTacoTranslateStaticProps یا getTacoTranslateServerSideProps استفاده خواهید کرد.

این توابع سه آرگومان می‌گیرند: یک شیء Next.js Static Props Context، پیکربندی برای TacoTranslate، و خواص اختیاری Next.js. توجه کنید که revalidate در getTacoTranslateStaticProps به‌طور پیش‌فرض روی 60 تنظیم شده است، تا ترجمه‌های شما به‌روز بمانند.

برای استفاده از هر یک از این توابع در یک صفحه، فرض کنیم شما یک فایل صفحه مانند /pages/hello-world.tsx دارید.

/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!"/>
}

مرحلهٔ ۵: استقرار و آزمایش!

تمام شد! برنامهٔ React شما اکنون به‌طور خودکار زمانی که هر رشته‌ای را به یک کامپوننت Translate اضافه می‌کنید، ترجمه خواهد شد. توجه داشته باشید که تنها محیط‌هایی که اجازهٔ read/write روی کلید API را دارند، قادر خواهند بود رشته‌های جدیدی را برای ترجمه ایجاد کنند. ما توصیه می‌کنیم یک محیط مرحله‌بندی (staging) بسته و امن داشته باشید که در آن بتوانید برنامهٔ تولیدی خود را با چنین کلید API بررسی کنید و قبل از رفتن به حالت زنده رشته‌های جدید اضافه نمایید. این کار از دزدیده شدن کلید API محرمانهٔ شما توسط هر کسی جلوگیری می‌کند و همچنین مانع از بزرگ یا پرحجم شدن بی‌مورد پروژهٔ ترجمه‌تان به‌خاطر اضافه شدن رشته‌های جدید و نامرتبط می‌شود.

حتماً مثال کامل را در پروفایل GitHub ما مشاهده کنید. آن‌جا همچنین نمونه‌ای را خواهید یافت که چگونه این کار را با استفاده از App Router انجام دهید! اگر با مشکلی مواجه شدید، خوشحال می‌شویم اگر با ما تماس بگیرید، و با کمال میل به شما کمک خواهیم کرد.

TacoTranslate به شما امکان می‌دهد برنامه‌های React خود را به‌طور خودکار و سریع به و از بیش از 75 زبان بومی‌سازی کنید. همین امروز شروع کنید!