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

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

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

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

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

با TacoTranslate به‌صورت خودکار برنامه‌های React خود را سریعاً به بیش از ۷۵ زبان مختلف بومی‌سازی کنید. امروز شروع کنید!