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

چگونه کار می‌کند

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

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

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

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

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

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