بهترین راه‌حل برای بین‌المللی‌سازی (i18n) در برنامه‌های Next.js

نحوهٔ کار

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

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

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

مرحله 1: یک کتابخانه i18n را نصب کنید.

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

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

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

npm install tacotranslate

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

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

در رابط کاربری برنامه TacoTranslate، یک پروژه ایجاد کنید و به زبانه کلیدهای API آن بروید. یک کلید read و یک کلید read/write بسازید. ما آن‌ها را به‌عنوان متغیرهای محیطی ذخیره خواهیم کرد. کلید read چیزی است که ما آن را public می‌نامیم و کلید read/write secret است. به‌عنوان مثال، می‌توانید آن‌ها را در فایل .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 اینجا را بخوانید.

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

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

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

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

تا کنون ما تنها برنامهٔ 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!"/>
}

مرحلهٔ پنجم: راه‌اندازی و آزمایش کنید!

تمام شد! اکنون اپلیکیشن Next.js شما به‌طور خودکار ترجمه خواهد شد وقتی هر رشته‌ای را به یک Translate کامپوننت اضافه کنید. توجه داشته باشید که تنها محیط‌هایی که مجوز read/write را روی کلید API دارند قادر خواهند بود رشته‌های جدیدی را برای ترجمه ایجاد کنند. ما توصیه می‌کنیم یک محیط استیجینگ بسته و امن داشته باشید تا بتوانید نسخه تولیدی خود را با چنین کلید 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 App 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!