كيفية تنفيذ التدويل في تطبيق Next.js الذي يستخدم Pages Router

مع ازدياد العولمة في العالم، أصبح من المهم بشكل متزايد لمطوري الويب بناء تطبيقات قادرة على تلبية احتياجات المستخدمين من دول وثقافات مختلفة. إحدى الطرق الرئيسية لتحقيق ذلك هي التدويل (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: “المجلد” حيث سيتم تخزين سلاسل النص الخاصة بك، مثل عنوان URL لموقعك. اقرأ المزيد عن الأصول هنا.

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

الخطوة 3: إعداد TacoTranslate

لدمج TacoTranslate مع تطبيقك، ستحتاج إلى إنشاء عميل باستخدام مفاتيح واجهة برمجة التطبيقات المذكورة سابقًا. على سبيل المثال، أنشئ ملفًا باسم /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, فيُرجى توسيع التعريف بإضافة الخصائص والكود المذكور أعلاه.

الخطوة 4: تنفيذ العرض من جانب الخادم

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

الخطوة 5: انشر واختبر!

لقد انتهينا! سيتم الآن ترجمة تطبيق React الخاص بك تلقائيًا عندما تضيف أي نصوص إلى مكوِّن Translate. لاحظ أن البيئات التي تمتلك أذونات read/write على مفتاح API فقط هي التي ستكون قادرة على إنشاء سلاسل جديدة للترجمة. نوصي بوجود بيئة اختبار (staging) مغلقة ومؤمّنة حيث يمكنك اختبار تطبيق الإنتاج الخاص بك باستخدام مفتاح API من هذا النوع، وإضافة نصوص جديدة قبل الإطلاق. سيمنع ذلك أي شخص أي شخص من سرقة مفتاح API السري الخاص بك، وقد يمنع أيضًا تضخيم مشروع الترجمة الخاص بك عبر إضافة سلاسل جديدة وغير ذات صلة.

تأكد من الاطلاع على المثال الكامل في صفحتنا على GitHub. هناك، ستجد أيضًا مثالًا يوضح كيفية القيام بذلك باستخدام App Router! إذا واجهت أي مشاكل، فلا تتردد في التواصل معنا، وسنكون سعداء جدًا بمساعدتك.

تتيح لك TacoTranslate توطين تطبيقات React تلقائيًا وبسرعة من وإلى أكثر من 75 لغة. ابدأ اليوم!