أفضل حل للتدويل (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: "المجلد" حيث سيتم تخزين سلاسل النص الخاصة بك، مثل عنوان 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, إعدادات لتكو تيرنسليت، وخصائص اختيارية من نكست.جي إس. لاحظ أن قيمة 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: النشر والاختبار!

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

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

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