كيفية تنفيذ التدويل في تطبيق Next.js الذي يستخدم App Router
اجعل تطبيق React الخاص بك أكثر سهولة للوصول وحقق انتشاراً في أسواق جديدة من خلال التدويل (i18n).
مع تزايد عولمة العالم، أصبح من المهم بشكل متزايد لمطوري الويب بناء تطبيقات تلبي احتياجات المستخدمين من بلدان وثقافات مختلفة. واحدة من الطرق الرئيسية لتحقيق ذلك هي من خلال التدويل (i18n)، الذي يتيح لك تكييف تطبيقك مع لغات مختلفة، وعملات، وصيغ تواريخ متنوعة.
في هذا المقال، سنستعرض كيفية إضافة التدويل إلى تطبيق React Next.js الخاص بك، مع تقديم الخادم (server side rendering). TL;DR: شاهد المثال الكامل هنا.
هذا الدليل مخصص لتطبيقات Next.js التي تستخدم App Router.
إذا كنت تستخدم Pages 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 مع تطبيقك، ستحتاج إلى إنشاء عميل باستخدام مفاتيح 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_IS_PRODUCTION === 'true'
? process.env.TACOTRANSLATE_PROJECT_LOCALE
: undefined,
});
module.exports = tacoTranslate;
سنقوم تلقائيًا بتعريف TACOTRANSLATE_API_KEY
و TACOTRANSLATE_PROJECT_LOCALE
قريبًا.
إنشاء العميل في ملف منفصل يجعل من السهل استخدامه مرة أخرى لاحقًا. getLocales
هي مجرد دالة مساعدة تحتوي على بعض معالجة الأخطاء المدمجة. الآن، قم بإنشاء ملف باسم /app/[locale]/tacotranslate.tsx
, حيث سنقوم بتنفيذ موفر TacoTranslate
.
'use client';
import React, {type ReactNode} from 'react';
import {
type TranslationContextProperties,
TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';
export default function TacoTranslate({
locale,
origin,
localizations,
children,
}: TranslationContextProperties & {
readonly children: ReactNode;
}) {
return (
<ImportedTacoTranslate
client={tacoTranslateClient}
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</ImportedTacoTranslate>
);
}
لاحظ 'use client';
مما يشير إلى أن هذا مكون للعميل.
مع وجود مزود السياق جاهز الآن، قم بإنشاء ملف باسم /app/[locale]/layout.tsx
, وهو التخطيط الجذري في تطبيقنا. لاحظ أن هذا المسار يحتوي على مجلد يستخدم Dynamic Routes, حيث [locale]
هو المعامل الديناميكي.
import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';
export async function generateStaticParams() {
const locales = await tacoTranslateClient.getLocales();
return locales.map((locale) => ({locale}));
}
type RootLayoutParameters = {
readonly params: Promise<{locale: Locale}>;
readonly children: ReactNode;
};
export default async function RootLayout({params, children}: RootLayoutParameters) {
const {locale} = await params;
const origin = process.env.TACOTRANSLATE_ORIGIN;
const localizations = await tacoTranslateClient.getLocalizations({
locale,
origins: [origin /* , other origins to fetch */],
});
return (
<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
<body>
<TacoTranslate
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</TacoTranslate>
</body>
</html>
);
}
أول شيء يجب ملاحظته هنا هو أننا نستخدم معامل Dynamic Route
الخاص بنا [locale]
لجلب الترجمات لتلك اللغة. بالإضافة إلى ذلك، يضمن generateStaticParams
أن جميع رموز اللغة التي قمت بتنشيطها لمشروعك تم توليدها مسبقًا.
الآن، لنقم ببناء صفحتنا الأولى! أنشئ ملفًا باسم /app/[locale]/page.tsx
.
import React from 'react';
import {Translate} from 'tacotranslate/react';
export const revalidate = 60;
export default async function Page() {
return (
<Translate string="Hello, world!" />
);
}
لاحظ متغير revalidate
الذي يخبر Next.js بإعادة بناء الصفحة بعد 60 ثانية، والحفاظ على تحديث ترجماتك.
الخطوة 4: تنفيذ عرض الخادم الجانبي
يدعم TacoTranslate العرض من جانب الخادم. هذا يحسن تجربة المستخدم بشكل كبير من خلال عرض المحتوى المترجم فورًا، بدلاً من وميض المحتوى غير المترجم أولاً. بالإضافة إلى ذلك، يمكننا تخطي طلبات الشبكة على العميل، لأننا بالفعل نمتلك الترجمات التي نحتاجها للصفحة التي يشاهدها المستخدم.
لإعداد العرض من جانب الخادم، أنشئ أو عدل ملف /next.config.js
:
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = await withTacoTranslate(
{},
{
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'),
}
);
// NOTE: Remove i18n from config when using the app router
return {...config, i18n: undefined};
};
قم بتعديل فحص isProduction
ليناسب إعداداتك. إذا كان true
, سيعرض TacoTranslate مفتاح API العام. إذا كنا في بيئة محلية أو اختبارية أو تجريبية (isProduction
is false
)، سنستخدم مفتاح API السري read/write
لضمان إرسال السلاسل الجديدة للترجمة.
لضمان أن يعمل التوجيه وإعادة التوجيه كما هو متوقع، سنحتاج إلى إنشاء ملف باسم /middleware.ts
. باستخدام Middleware, يمكننا إعادة توجيه المستخدمين إلى صفحات معروضة بلغتهم المفضلة.
import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';
export const config = {
matcher: ['/((?!api|_next|favicon.ico).*)'],
};
export async function middleware(request: NextRequest) {
return tacoTranslateMiddleware(tacoTranslate, request);
}
تأكد من إعداد matcher
وفقًا لـ وثائق وسيط Next.js.
على العميل، يمكنك تعديل ملف تعريف الارتباط locale
لتغيير اللغة المفضلة للمستخدم. يرجى الاطلاع على كود المثال الكامل للحصول على أفكار حول كيفية القيام بذلك!
الخطوة 5: النشر والاختبار!
لقد انتهينا! سيتم الآن ترجمة تطبيق React الخاص بك تلقائيًا عند إضافة أي نصوص إلى مكون Translate
. لاحظ أنه فقط البيئات التي تمتلك أذونات read/write
على مفتاح API ستكون قادرة على إنشاء نصوص جديدة للترجمة. نوصي بوجود بيئة اختبار مغلقة ومؤمّنة حيث يمكنك اختبار تطبيق الإنتاج الخاص بك باستخدام مفتاح API من هذا النوع، وإضافة نصوص جديدة قبل النشر. سيمنع هذا أي شخص من سرقة مفتاح API السري الخاص بك، ومن زيادة حجم مشروع الترجمة الخاص بك بإضافة نصوص جديدة غير ذات صلة.
تأكد من الاطلاع على المثال الكامل على ملفنا في GitHub. هناك، ستجد أيضًا مثالاً على كيفية القيام بذلك باستخدام Pages Router ! إذا واجهت أي مشاكل، لا تتردد في التواصل معنا، وسنسعد بمساعدتك.
يتيح لك TacoTranslate تعريب تطبيقات React الخاصة بك تلقائيًا بسرعة من وإلى أي لغة. ابدأ اليوم!