التدويل (i18n)
كيف يُعلِن موقع وثائق Apothem مجموعة لغاته، ويُصدِر روابط hreflang للغات البديلة، ويَعرض من اليمين إلى اليسار عبر اثنتي عشرة لغة.
توثّق هذه الصفحة كيف يتعامل موقع وثائق Apothem مع لغات متعددة: مجموعة
اللغات التي يُعلنها، وآلية hreflang التي يُصدِرها، وعرضه من اليمين إلى
اليسار، وكيف تُوصَل صفحات كل لغة بالتوجيه.
ملخّص القرار
- المنصّة: Next.js App Router + Fumadocs. يُبنى الموقع من
site/. تُعلَن مجموعة اللغات فيsite/lib/i18n.ts، وتعيش آلية روابط اللغات البديلة فيsite/lib/hreflang.ts. - مجموعة اللغات: اثنتا عشرة لغة. مجموعة المطوّر الحديثة المكوّنة من اثنتي عشرة
لغة هي مصدر الحقيقة القانوني، والإنجليزية هي لغة المصدر، وكلٌّ من اللغات الإحدى عشرة
المستهدفة مبذورة آليًا من مجموعة الصفحات الإنجليزية؛ والمراجعة البشرية لكل لغة
جارية، ويغطّي
fallbackLanguage: 'en'أي صفحة لم تؤلّفها لغة ما بعد. - التوجيه لكل لغة: مُفعَّل عبر المجموعة. كل لغة موصولة بالتوجيه ويمكن الوصول
إليها عند بادئة URL الخاصة بها (
/es/،/zh-cn/، …)؛ وتُقدَّم الإنجليزية في جذر الموقع. - آلية
hreflang: فعّالة. تُصدِر كل صفحة مجموعة<link rel="alternate">تغطّي كل لغة إضافةً إلى بديل احتياطيx-default، فترى محرّكات البحث عنقود اللغات البديلة كاملًا. وتُحَلّ الروابط لكل ملف من نظام الملفات، فلا يُعلَن عن صفحة في لغة ما إلا حين تمتلكها تلك اللغة. - العرض من اليمين إلى اليسار: فعّال. تستخدم أوراق الأنماط المشتركة خصائص
CSS المنطقية في كل مكان، فتُعرَض الصفحات العربية على نحو صحيح تحت
dir="rtl". - مراجعة الترجمة: مُتتبَّعة لكل صفحة. تُقدَّم صفحات اللغات المبذورة آليًا وتحمل
machineTranslated: trueفي بياناتها الأمامية إلى أن يراجعها إنسان؛ وهذه العلامة بيانات وصفية لتتبّع المراجعة ولا تعرضها الصفحة. والإنجليزية هي البديل الاحتياطي لأي صفحة تفتقر إليها لغة ما. ومراجعة 80% من صفحات لغة ما هدفٌ للمراجعة، لا شرطٌ للنشر. - حداثة الترجمة: مُتتبَّعة لكل صفحة. تُسجّل كل صفحة لغوية النص الإنجليزي الذي تُرجمت منه. وحين تتغيّر الصفحة الإنجليزية لاحقًا، تعرض الصفحة المترجَمة ملاحظة من سطر واحد تربط بالصفحة الإنجليزية، التي تبقى المرجع المعتمد.
مجموعة اللغات
تُعلِن مجموعة المطوّر الحديثة اثنتي عشرة لغة. تُقدَّم الإنجليزية في جذر الموقع؛ وكلٌّ
من اللغات الإحدى عشرة المستهدفة مبذورة آليًا من مجموعة الصفحات الإنجليزية عند بادئة
URL الخاصة بها، ويغطّي fallbackLanguage: 'en' أي صفحة لم
تُؤلَّف بعد.
| الرمز | المسار | اللغة | الاتجاه |
|---|---|---|---|
en | / | الإنجليزية | LTR |
zh-CN | /zh-cn/ | الصينية المبسّطة | LTR |
es | /es/ | الإسبانية | LTR |
pt-BR | /pt-br/ | البرتغالية البرازيلية | LTR |
fr | /fr/ | الفرنسية | LTR |
de | /de/ | الألمانية | LTR |
ja | /ja/ | اليابانية | LTR |
ko | /ko/ | الكورية | LTR |
ru | /ru/ | الروسية | LTR |
id | /id/ | الإندونيسية | LTR |
ar | /ar/ | العربية | RTL |
hi | /hi/ | الهندية | LTR |
المجموعة هي مصدر الحقيقة الوحيد؛ وتمرّ التعديلات عليها عبر قرار متعمَّد، ولا تمرّ أبدًا عبر تحرير صامت.
كيف تعمل hreflang
يبني site/lib/hreflang.ts خريطة alternates.languages التي
يعرضها Next.js في <head> كل صفحة. ويلتزم بناؤها بقاعدة واحدة:
يُصدَر رابط اللغة البديلة للغةٍ ما فقط حين تكون تلك اللغة قد ألّفت تلك الصفحة،
ويُحَلّ ذلك لكل ملف من نظام الملفات (site/lib/translated-pages.ts).
ولذلك تُصدِر الصفحة المترجَمة بالكامل العنقود كاملًا:
<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="es" href="https://apothem.ahmedgad.com/es/..." />
<link rel="alternate" hreflang="ar" href="https://apothem.ahmedgad.com/ar/..." dir="rtl" />
<!-- … one per cohort locale … -->
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />رابط canonical للصفحة هو دائمًا عنوان URL الخاص بها — ولا
يشير أبدًا عبر اللغات.
العرض من اليمين إلى اليسار
العربية هي لغة المجموعة التي تُكتَب من اليمين إلى اليسار، ويعرضها الموقع على نحو صحيح:
- خصائص CSS المنطقية فقط. تستخدم أوراق الأنماط والمكوّنات المشتركة
خصائص منطقية (
margin-inline-start، وpadding-inline-end، وtext-align: start، وinset-inline-start) بدلًا من الخصائص الفيزيائية (margin-left، وtext-align: left). تنقلب الخصائص المنطقية تلقائيًا تحتdir="rtl"، فتخدم ورقة الأنماط نفسها الاتجاهين كليهما على نحو صحيح. - سمة الاتجاه. تضبط الصفحات العربية
dir="rtl"على العنصر<html>إلى جانبlang="ar". - المحتوى ثنائي الاتجاه. السلاسل مختلطة الاتجاه — مثل أمر إنجليزي داخل فقرة
عربية — تُغلَّف في
<bdi>كي يُعرَض المقطع المضمَّن من اليسار إلى اليمين على نحو صحيح ضمن التدفّق من اليمين إلى اليسار.
إضافة لغة أو تحديثها
يقود site/lib/i18n.ts المجموعةَ والتوجيه:
- ألّف الصفحة تحت
content/docs/<locale>/بحيث تعكس المصدر الإنجليزي. - سجّل النص الإنجليزي الذي تترجمه: من
site/، شغّلnode scripts/translation-sources.mjs --stamp <locale>/<path>.mdx، الذي يكتب بصمة الصفحة الإنجليزية في حقلsourceHashضمن البيانات الأمامية للصفحة اللغوية. - تأكّد من أن اللغة مُدرَجة في
ROUTED_LOCALES(لغات المجموعة الاثنتا عشرة كلها موجَّهة اليوم). - يُحَلّ رابط
hreflangالخاص بها ومساراتها تلقائيًا من نظام الملفات.
الترجمات المتقادمة
الحقل sourceHash في الصفحة اللغوية هو بصمة الصفحة الإنجليزية التي تُرجمت
منها، وهي تغطّي البيانات الأمامية والنثر الإنجليزيين، لا الجداول المولَّدة التي يعيد
مولّد المرجع كتابتها في كل اللغات دفعة واحدة. وعند البناء يحسب الموقع بصمة الصفحة
الإنجليزية الحالية؛ وحين تختلف البصمتان، تعرض الصفحة المترجَمة ملاحظة بأن الصفحة
الإنجليزية تغيّرت منذ إعداد الترجمة، مع رابط إليها. شغّل
node scripts/translation-sources.mjs من site/ لسرد الصفحات
المتقادمة لكل لغة، ثم حدّث كل ترجمة واختمها كما في الخطوة 2 أعلاه. والصفحة التي لم
تترجمها لغة ما على الإطلاق تُقدَّم من المصدر الإنجليزي، موسومةً بأنها نص إنجليزي.
تبقى الإنجليزية مصدر الحقيقة؛ وتعكس كل صفحة لغوية بنية نظيرتها الإنجليزية وروابطها وعيّنات شيفرتها حرفيًا.