تدويل Rails من عناوين URL لكي

يأتي Rails مزودًا بإطار عمل للتدويل مدمج فيه. ولا تحتاج أكثر لكي – فواجهة برمجة تطبيقات I18n هي جزء من المجموعة، وتقوم بمعالجة الأساسيات بشكل جيد: ترجمة السلاسل الثابتة، وتنسيق التواريخ والأرقام، وإدارة صيغ الجمع عبر اللغات المختلفة.

لكن مصطلح "مُدمج" لا يعني "كامل". ففي اللحظة التي تتوسع فيها متطلباتك لكي عناوين URL لكي ، أو ترجمات JavaScript، أو تحسين محركات البحث متعدد اللغات، فإنك تعمل خارج ما يوفره ما بشكل أساسي. وتستلزم هذه الثغرات اتخاذ قرارات هندسية مدروسة.

دعونا نستعرض كلا الطبقتين: ما تتولى ما برمجة تطبيقات I18n ما Rails معالجته، والأماكن التي ستحتاج لكي – أو تفويض المهمة.

ما يغطيه ما (I18n) وما هي حدوده

توفر واجهة برمجة التطبيقات I18n طريقتين أساسيتين: I18n.t لترجمة السلاسل النصية وI18n.l لتعريب التواريخ والأرقام. وتقوم كلتا الطريقتين بقراءة ملفات YAML أو Ruby الموجودة في المجلد config/locales/، ويقوم Rails بتحميلها تلقائيًا عند بدء التشغيل.

بشكل افتراضي، يشمل ذلك سلاسل واجهة المستخدم الثابتة، وتنسيق التواريخ والأرقام، ورسائل التحقق من صحة البيانات في ActiveRecord. وبالنسبة لمعظم المشاريعلكي فإن هذا يكفي لكي .

تظهر الثغرات بسرعة بمجرد التعمق في الموضوع.

لا يتدخل Rails I18n في بنية عناوين URL: فلا يوجد مسارات مترجمة، ولا اكتشاف للنطاقات الفرعية، ولا بادئات للمسارات. كما أنه لا يحتوي على آلية لترجمة المحتوى المخزن في قاعدة البيانات، مثل أسماء المنتجات أو منشورات المدونة. وتقع ملفات JavaScript خارج نطاق مسار المعالجة تمامًا. أما تحسين محركات البحث متعدد اللغات، مثل علامات hreflang والعناوين المختصرة المترجمة وخرائط المواقع الخاصة بكل لغة، فتتطلب عملاً منفصلاً لا يتدخل فيه الإطار.

يجب لكي أين تقع الحدود قبل أن تبدأ في البناء.

إعداد أساس الترجمة الدولية (I18n)

يمكنك البدء باستخدام المكتبة rails-i18n.

فقط Rails بيانات الإعدادات المحلية باللغة الإنجليزية فقط ؛ لذا، بدونها، تفشل دالة I18n.l(Date.today) في الإعدادات المحلية غير الإنجليزية، وتظل السلاسل النصية على مستوى الإطار، مثل رسائل التحقق من صحة البيانات في Active Record، باللغة الإنجليزية بغض النظر عن الإعدادات المحلية الحالية.

# ملف Gemfile

gem "rails-i18n"

ثم قم بتكوين الإعدادات الافتراضية لتطبيقك:

# config/application.rb

config.i18n.default_locale = :en

config.i18n.available_locales = [:en, :fr]

config.i18n.enforce_available_locales = true

تؤدي قيمة enforce_available_locales = true إلى ظهور خطأ إذا حاول تطبيقك لكي لغة خارج تلك القائمة. وبدونها، قد يؤدي خطأ مطبعي أو معلمة URL غير صحيحة إلى تعيين لغة غير مدعومة في بيئة الإنتاج دون ظهور أي إشعار.

على الرغم من أن Rails الحديثة تقوم بالمسح حتى المستوى الأول، إلا أنها غالبًا ما تتجاهل المجلدات المتداخلة بعمق (مثل config/locales/views/products/). تضمن إضافة هذا السطر تضمين كل دليل فرعي مع نمو تطبيقك:

config.i18n.load_path += Dir[Rails.root.join("config", "locales", "**"، "*.{rb,yml}")]

يتيح لك هذا تقسيم ملفات الترجمة حسب المجال:

config/locales/  
	en/    
		models.yml    
		views.yml    
		mailers.yml  
	fr/    
		models.yml    
		views.yml    
		mailers.yml

⚠️ يقوم YAML بتحليل القيم مثل true و false على أنها قيم منطقية. إذا كنت بحاجة إليها كنص حرفي، فقم بوضعها بين علامتي اقتباس بشكل صريح. تعامل الإصدارات الحديثة من Ruby/YAML الآن نعم no على أنهما سلاسل نصية، لكن وضعها بين علامتي اقتباس يظل عادة آمنة من أجل التوافق:

en:  
	الإجابات:    
		إيجابي: "نعم"    
		سلبي: "لا"

هذا يكتشف فئة من الأخطاء التي فقط عندما "true" بدلاً من "نعم" ولا تعرض واجهة العرض أي شيء، أو الأسوأ من ذلك، تعرض السلسلة "true".

أدوات المساعدة في الترجمة والبحث المؤجل في "Views"

في القوالب، يُعد كل من t و l المساعدين اللذين ستستخدمهما باستمرار.

تقوم الدالة l بتعريب التواريخ والأوقات والأرقام لكي الحالية. عند تثبيت rails-i18n، يتم تضمين تعريفات التنسيق لأكثر من 100 لغة. وبدونها، فإن استدعاء l(Date.today) في إعدادات محلية غير الإنجليزية سيعرض عادةً سلسلة "ترجمة مفقودة" أو تاريخًا غير منسق، حيث تفتقر Rails إلى أنماط التنسيق المُعَرَّبة اللازمة.

<%= l(Date.today) %>

<%= l(Date.today, format: :long) %>

تقوم t بترجمة السلاسل حسب المفتاح. الصيغة الكاملة هي t("products.index.title")، ولكن في العروض يمكنك استخدام الاختصار "البحث المتأخر":

<%= t(".title") %>

تُعلم النقطة في بداية المفتاح نظام Rails لكي المفتاح لكي الحالي. في ملف app/views/products/index.html.erb، يتم توسيع t(".title") تلقائيًا لكي ("products.index.title"). وهذا يحافظ على قصر المفاتيح ويضمن اتباع قواعد تسمية متسقة دون بذل جهد إضافي.

For interpolation, use %{variable} in your YAML and pass the value as a keyword argument:

en:  
	welcome: "Hello, %{name}"

<%= t(".welcome", name: current_user.name) %>

إذا كانت الترجمة تحتوي على كود HTML تثق به، فقم بإضافة _html لكي المفتاح. سيقوم Rails بوضع علامة "آمن" عليه تلقائيًا، دون الحاجة إلى استدعاء html_safe.

en:  
	notice_html: "Please <strong>confirm</strong> your email."

فقط "Lazy lookup" فقط عندما يكون بإمكان Rails استنتاج مسار العرض، مما يعني أنه لا يعمل في المهام الخلفية ووحدات التحكم في واجهة برمجة التطبيقات (API). في هذه الحالات، استخدم المفتاح الكامل في كل مرة.

اختيار استراتيجية تحديد الإعدادات الإقليمية

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

تعد بادئة المسار، مثل /fr/products، الخيار الأكثر شيوعًا لتطبيقات Rails الموجهة للجمهور. فهي تحافظ على الإشارة الصريحة إلى الإعدادات المحلية في كل عنوان URL، مما يتيح لمحركات البحث فهرستها بشكل مستقل حسب اللغة.

تُعد استراتيجيات النطاقات الفرعية ونطاقات المستوى الأعلى فعالة عندما تعزيز الهوية الإقليمية، لكنها تفرض أعباءً إضافية تتعلق بتكوين نظام أسماء النطاقات (DNS) وشهادات SSL.

تعد معلمات عناوين URL، مثل /products?locale=fr، مناسبة للأدوات الداخلية التي لا يُعد تحسين محركات البحث (SEO) فيها أمراً مهماً.

تعمل الإعدادات المفضلة المخزنة في قاعدة البيانات مع التطبيقات التي تتطلب المصادقة، حيث تتبع الإعدادات اللغوية المستخدم، وليس عنوان URL.

أياً كانت الاستراتيجية التي تختارها، هناك خطأ واحد في التنفيذ يتسبب في حدوث أخطاء خفية في بيئة الإنتاج: وهو استخدام I18n.locale = بشكل مباشر.

# Don't do this

before_action { I18n.locale = params[:locale] }

I18n.locale = يكتب لكي .current.

إذا كنت تستخدم خادم ويب Puma، فإنه يعيد استخدام الخيوط عبر الطلبات. وإذا لم يحدد الطلب الإعدادات الإقليمية صراحةً، فإنه يرث الإعدادات التي تركها الطلب السابق.

في بيئة التطوير المحلية التي تعمل بخيط واحد، لا يظهر هذا المشكل أبدًا. أما في بيئة الإنتاج، فيؤدي إلى ظهور ردود متقطعة بلغة خاطئة يصعب لكي ويصعب لكي .

استخدم I18n.with_locale داخل دالة around_action بدلاً من ذلك:

around_action :switch_locale‍d


ef switch_locale(&action)  
	locale = params[:locale] || I18n.default_locale  
	I18n.with_locale(locale, &action)
end

تعمل وظيفة `with_locale` على استعادة الإعدادات المحلية السابقة بعد انتهاء الكتلة، بغض النظر عن كيفية انتهاء الطلب.

تنفيذ المسارات المُترجمة محليًّا واكتشاف النطاقات الفرعية

حدد مساراتك ضمن /:locale وقم بتجاوز الإعدادات الافتراضية لـ default_url_options حتى تضيف Rails تلقائيًا الإعدادات المحلية الحالية لكي مساعد URL:

# config/routes.rb
scope "/:locale" do
  resources :products
  root "home#index"
end

# app/controllers/application_controller.rb
around_action :switch_locale

def switch_locale(&action)
  locale = params[:locale]
  # Fallback to default if the param is missing or unsupported
  valid_locale = I18n.available_locales.map(&:to_s).include?(locale) ? locale : I18n.default_locale
  I18n.with_locale(valid_locale, &action)
end

def default_url_options
  { locale: I18n.locale }
end

عند تعيين default_url_options، يتم عرض products_path تلقائيًا على النحو التالي: /fr/products عندما تكون عندما المحلية الحالية هي :fr.

إذا كنت تريد لكي الإعدادات المحلية الافتراضية البادئة، فاجعل المقطع اختياريًا بنطاق "(:locale)". وهذا يعرض /products للغة الإنجليزية و/fr/products للغة الفرنسية، لكنه يضيف بعض الغموض. فقد يتطابق مسار مثل /about إما مع إعدادات محلية مفقودة أو مع وحدة تحكم باسم about، اعتمادًا على ترتيب المسارات لديك.

للكشف عن النطاقات الفرعية، اقرأ من request.subdomains.first وقارنها بقائمة available_locales قبل إجراء أي إعدادات:

def استخراج_اللغة_من_النطاق_الفرعي
  subdomain = request.subdomains.first
  return nil إذا subdomain.blank? || subdomain == "www"
  subdomain إذا I18n.available_locales.map(&:لكي).include?(subdomain)
end

يمنع فحص www من معاملته كإعدادات لغة. على localhost، تُرجع request.subdomains مصفوفة فارغة، لذا يفشل اكتشاف النطاقات الفرعية في بيئة التطوير ما لم تستخدم خادم Pow أو تضيف إدخالات لكي ملف /etc/hosts.

هناك أمر واحد لكي بشكل منفصل: لا تنتقل قيمة `default_url_options` المُعرَّفة في `ApplicationController` لكي أو المهام الخلفية. لذا، يجب تعيينها صراحةً في تلك السياقات:

Rails.application.routes.default_url_options = { host: "example.com", locale: :en }

توفر لك المسارات المُترجمة بنية عناوين URL، لكن علامات hreflang وعناوين الروابط المُترجمة وخرائط المواقع متعددة اللغات تظل تُدار يدويًا بالكامل بعد هذا الإعداد.

يتولى تكامل الوكيل العكسي Weglot هذه الطبقة تلقائيًا، حيث يقوم بإنشاء علامات hreflang وعناوين URL الخاصة باللغة دون الحاجة إلى إعدادات إضافية.

التعددية، والبدائل، ومكتبة rails-i18n

تعد صيغة الجمع في اللغة الإنجليزية بسيطة. فهناك صيغة واحدة للمفرد، وصيغة واحدة لكل ما عدا ذلك.

en:
  messages:
    one: "%{count} message"
    other: "%{count} messages"

معظم اللغات ليست بهذه البساطة.

في اللغة البلغارية، على مثل، توجد صيغة الجمع العادية وصيغة "الجمع العددي" الخاصة ببعض الكلمات في صيغة المذكر. لذا، فإن كلمة «ден» (يوم) تصبح «дни» (أيام) في العادة، ولكنها تصبح «два дена» (يومان) عندما .

bg:
  cities:
    one: "%{count} ден"
    few: "%{count} дена"
    many: "%{count} дни"

بدون مكون rails-i18n، لا يكون لدى Rails أي علم بهذه القواعد. وستظهر أخطاء في ترجماتك البلغارية أو ستعود إلى استخدام لكي الآخر) في كل حالة.

تقوم مكتبة Gem بتوفير منطق صيغة الجمع لأكثر من 100 لغة، بحيث يتم عرض النصوص بشكل صحيح باللغات البلغارية والروسية والعربية والبولندية وأي لغة أخرى تتبع قواعد جمع مختلفة عن اللغة الإنجليزية.

تُعد الخيارات البديلة مسألة منفصلة، وهي معطلة بشكل افتراضي. وبدونها، فإن أي مفتاح ترجمة مفقود سيؤدي إلى ظهور رسالة "ترجمة مفقودة" في بيئة الإنتاج. وهذا النوع من الأمور قد يصل إلى المستخدمين ويظهر في لقطات الشاشة.

قم بتمكين الخيارات البديلة وحدد وجهة افتراضية في ملف config/application.rb:

config.i18n.fallbacks = [I18n.default_locale]

عند تعيين الخيار fallbacks على القيمة true، يتم اللجوء لكي في حالة عدم وجود مفتاح في الإعدادات المحلية الحالية. بالنسبة للمتغيرات الإقليمية، يمكنك تعريف سلاسل صريحة:

config.i18n.fallbacks = { "fr-CA": :fr, "en-GB": :en }

قم بتكوين هذا في مرحلة مبكرة. فإضافة سلوك احتياطي إلى تطبيق يحتوي بالفعل على ترجمات جزئية قيد التشغيل أصعب من إعداده منذ البداية.

ترجمة مؤقتة لكي وحدات التحكم لكي وجافا سكريبت

لا يمكن لـ JavaScript الوصول لكي مسار I18n لكي Rails.

لا يوجد مساعد t أو أداة تحميل YAML أو جسر مدمج بين ملفات الترجمة ووحدات التحكم في Stimulus. لكي الترجمات بشكل صريح من جانب الخادم.

أبسط طريقة لاستخدام Stimulus هي واجهة برمجة التطبيقات (API) الخاصة بالقيم. قم بتعريف الترجمة كقيمة في وحدة التحكم، وقم بتعيينها في HTML، ثم اقرأها في JavaScript:

# app/views/products/index.html.erb
<div data-controller="notification"
     data-notification-message-value="<%= t('.success_message') %>">

يتم عرض القيمة من جانب الخادم باستخدام المساعد القياسي t، لذا فهي تتوافق تلقائيًا مع الإعدادات المحلية الحالية. أما من جانب JavaScript، فيجب تعريفها كقيمة ثابتة وقراءتها عبر واجهة برمجة التطبيقات (API) الخاصة بالقيم:

// app/javascript/controllers/notification_controller.js
export default class extends Controller {
  static values = { message: String }

  show() {
    alert(this.messageValue)
  }
}

كل ترجمة واضحة ومحددة النطاق لكي التحكم التي تحتاج إليها. ولا يتسرب أي شيء إلى النطاق العام.

إذا احتاج المبرمج إلى عدة ترجمات في آن واحد، فإن تجميعها كسمة بيانات JSON يعد أسلوبًا أكثر إتقانًا من إضافة تعريفات قيم فردية لكل سلسلة نصية:

<div data-controller="cart"
     data-cart-i18n-value="<%= { add: t('.add'), remove: t('.remove') }.to_json %>">

في جانب جافا سكريبت، قم بتعريف i18n كقيمة كائن والوصول إلى المفاتيح الفردية مباشرةً:

static values = { i18n: Object }

add() {
  console.log(this.i18nValue.add)
}

بالنسبة للتطبيقات التي تتطلب لغة جافا سكريبت وصولاً واسعاً إلى ملفات الترجمة عبر العديد من وحدات التحكم، تقوم مكتبة i18n-js بتصدير ملفات YAML الخاصة بك لكي جافا سكريبت يمكنك الاستعلام عنه باستخدام I18n.t("key").

إنها تعمل، لكنها تضيف خطوة إضافية في عملية البناء وترسل مجموعة الترجمة الكاملة لكي . استخدمها عندما يصبح عندما متكررين، وليس كخيار افتراضي.

عندما Turbo Frames، إذا كان عنوان URL لمصدر Turbo Frame لا يتضمن بادئة الإعدادات المحلية، فسيفشل الطلب عادةً مع ظهور خطأ في التوجيه (404) لأنه لن يتطابق مع نمط نطاقك "/:locale". استخدم دائمًا مساعدات المسار التي تراعي الإعدادات المحلية لمصادر الإطارات.

هذا ليس خطأً في Turbo. بل هو سهو في التوجيه، وتقوم وظيفة `around_action` الموجودة في قسم الكشف عن الإعدادات المحلية بمنع حدوثه طالما أن كل عنوان URL في الإطار يستخدم مساعد مسار يدعم الإعدادات المحلية.

يتبع الوكيل العكسي Weglot نهجًا مختلفًا تمامًا. فهو يقوم بترجمة نموذج DOM المعروض بعد تحميل الصفحة، وبالتالي يتم تغطية المحتوى المعروض بواسطة Stimulus والسلاسل التي يتم إدراجها ديناميكيًا دون الحاجة إلى أي من هذه التوصيلات.

ما لا تتناوله ميزة I18n ما

هناك ثلاث فئات تقع تمامًا خارج نطاق ما تتعامل معه ميزة I18n ما :

• تحويل SEO متعدد اللغات في Rails i18n يقوم بترجمة السلاسل النصية، لكنه لا يُنشئ علامات hreflang أو خرائط مواقع خاصة بكل لغة أو بيانات وصفية مترجمة. وتتطلب هذه المهام عملاً يدويًا يتجاوز إعدادات i18n.
• لا يمكن تخزين المحتوى المخزّن في قاعدة البيانات، مثل أسماء المنتجات ومنشورات المدونة، في ملفات YAML. يُوصى باستخدام مكتبة Mobility لهذا الغرض، حيث إنها تدعم العديد من أنظمة التخزين الخلفية. وتُعد Traco بديلاً أخف وزناً للنماذج الأصغر حجماً التي تتضمن ترجمات لكل عمود على حدة.
• يعتمد سير عمل الترجمة في Rails على ملفات YAML. ويجب أن تتم إدارة عملية الترجمة ودورات المراجعة والتحديثات، فضلاً عن الحفاظ على تزامن الترجمات مع التطبيق، خارج نطاق إطار العمل.

Weglot يعالج كل هذه الأمور في طبقة الإخراج بدلاً من طبقة الكود:

• بدلاً من الاندماج مع مسار Rails I18n، يقوم هذا المكون بترجمة كود HTML المعروض الذي تنتجه تطبيقك. وهذا يعني أن محتوى قاعدة البيانات، والسلاسل التي يتم عرضها بواسطة JavaScript، والترجمات الثابتة، يتم التعامل معها جميعًا بالطريقة نفسها.
• يتم تضمين خدمات تحسين محركات البحث (SEO) والموقع الجغرافي (GEO) متعددة اللغات: حيث يتم إنشاء علامات hreflang وعناوين URL المترجمة وخرائط المواقع تلقائيًا.
• يتم تنفيذ سير عمل المترجم عبر لوحة تحكم Weglot بدلاً من دورات تصدير ملفات YAML.

ومع ذلك، هناك بعض القيود التي يجدر بك معرفتها قبل تقييمه:

• لا يتم فهرسة snippet جافا سكريبت snippet ؛ لذا تحتاج إلى إعداد الوكيل العكسي للصفحات المترجمة لكي في نتائج البحث.
• تعد ميزة توجيه الدلائل الفرعية المخصصة، التي تُعد مفيدة إذا كان لديك تكوين CDN أو Nginx قائم بالفعل، متاحةفقط في الإصدار Enterprise.
• على عكس الترجمات المدمجة في قاعدة الكود الخاصة بك، Weglot اشتراكًا نشطًا لكي ظهور المحتوى المترجم.

اختيار بنية i18n في Rails

يتمثل كل تطبيق لـ i18n في Rails لكي اتخاذ نفس القرارات بنفس الترتيب تقريبًا.

أولاً، حدد استراتيجيتك الخاصة بعناوين URL قبل كتابة أي كود لاكتشاف الإعدادات المحلية. تعمل أجزاء المسار بشكل جيد مع معظم التطبيقات الموجهة للجمهور. وتكون النطاقات الفرعية خياراً مناسباً عندما تكون الهوية عندما عاملاً مهماً. أما التفضيلات المخزنة في قاعدة البيانات، فهي مناسبة للتطبيقات التي تتطلب تسجيل الدخول، حيث تتبع الإعدادات المحلية المستخدم بدلاً من عنوان URL.

ثانياً، حدد كيفية حصول جافا سكريبت على الترجمات. تغطي واجهة برمجة تطبيقات قيم Stimulus معظم الحالات. وتُستخدم سمات JSON عندما يحتاج عندما التحكم إلى عدة سلاسل نصية في آن واحد.

ثالثًا، حدد ما إنشاؤه يدويًّا. تتعامل Rails مع السلاسل الثابتة بشكل جيد. تتطلب طبقة تحسين محركات البحث (SEO) وسير عمل المترجم ومحتوى قاعدة البيانات اتخاذ قرارات منفصلة. يمكنك إنشاء كل منها بنفسك، أو تفويض مهمة طبقة الإخراج لكي مثل Weglot يز وقت فريق التطوير على التطبيق نفسه.

تخطَّ طبقة الإخراج تمامًا. جرَّب Weglot لمدة 14 يومًا واستفد من خدمات تحسين محركات البحث (SEO) والتوجيه الجغرافي (GEO) متعدد اللغات، وعناوين URL المترجمة، والكشف التلقائي عن المحتوى دون الحاجة إلى تعديل كود i18n الخاص بك.