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

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

با جهانی‌تر شدن دنیا، برای توسعه‌دهندگان وب هر روز اهمیت بیشتری دارد که اپلیکیشن‌هایی بسازند که بتوانند نیازهای کاربران از کشورهای و فرهنگ‌های مختلف را برآورده کنند. یکی از راه‌های کلیدی برای دستیابی به این هدف، بین‌المللی‌سازی (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: «پوشه‌ای» که رشته‌های شما در آن ذخیره خواهند شد، مانند آدرس وب‌سایت شما. در اینجا درباره origins بیشتر بخوانید.

.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 سفارشی دارید، لطفاً تعریف را با ویژگی‌ها و کدهای بالا گسترش دهید.

مرحله ۴: پیاده‌سازی رندر سمت سرور

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 اضافه کنید. توجه داشته باشید که تنها محیط‌هایی که در کلید API مجوز read/write دارند قادر به ایجاد رشته‌های جدید برای ترجمه خواهند بود. ما توصیه می‌کنیم یک محیط آزمایشی (staging) بسته و امن داشته باشید تا بتوانید برنامهٔ تولید (production) خود را با چنین کلید API آزمایش کرده و پیش از راه‌اندازی، رشته‌های جدید را اضافه کنید. این از دزدیده شدن کلید API محرمانهٔ شما توسط دیگران جلوگیری می‌کند و همچنین از پُر یا متورم شدن غیرضروری پروژهٔ ترجمه‌تان با رشته‌های جدید و نامرتبط پیشگیری می‌نماید.

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

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