أفضل حل للتدويل (i18n) في تطبيقات Next.js

كيف يعمل

مع تزايد عولمة العالم، أصبح من المهم بشكل متزايد لمطوري الويب بناء تطبيقات يمكنها تلبية احتياجات المستخدمين من دول وثقافات مختلفة. إحدى الطرق الرئيسية لتحقيق ذلك هي التدويل (i18n)، الذي يتيح لك تكييف تطبيقك لدعم لغات وعملات وتنسيقات تواريخ مختلفة.

في هذا الدرس، سنستعرض كيفية إضافة التدويل إلى تطبيق React Next.js الخاص بك مع العرض من جانب الخادم. TL;DR: شاهد المثال الكامل هنا.

هذا الدليل مخصص لتطبيقات Next.js التي تستخدم Pages Router.
إذا كنت تستخدم App Router, فالرجاء الاطلاع على هذا الدليل بدلاً من ذلك.

الخطوة 1: تثبيت مكتبة 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

الخطوة 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 العام. إذا كنا في بيئة محلية أو اختبارية أو بيئة تحضيرية (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!"/>
}

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

انتهينا! سيُترجم تطبيق Next.js الخاص بك الآن تلقائيًا عندما تضيف أي سلاسل نصية إلى مكوّن Translate. لاحظ أنّ البيئات التي تمتلك صلاحيات read/write على مفتاح الـ API فقط هي القادرة على إنشاء سلاسل جديدة للترجمة. نوصي بوجود بيئة اختبار مغلقة ومؤمّنة (staging) حيث يمكنك اختبار تطبيق الإنتاج باستخدام مثل هذا المفتاح، وإضافة السلاسل الجديدة قبل الإطلاق. هذا سيمنع أي شخص من سرقة مفتاح الـ 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!