مفاتيح الترجمة التي تظل متسقة عبر تطبيق كامل
كيف تسمي localize.dev المفاتيح، وتعيد استخدامها للنصوص المتكررة، وتحافظ على النصوص القصيرة الغامضة منفصلة، وتلاحظ عندما يتغير النص المصدر بعد ترجمته.
Stephen Ufort · 6 نوفمبر 2026 · دقيقتان للقراءة

المفاتيح المكتوبة يدويًا تنجرف. يكتب شخص save_button، وآخر buttons.save، وثالث common.actions.save، وتحمل ثلاثة مفاتيح نفس الكلمة. طلب وكيل ترميز لاستخراج السلاسل النصية ملفًا واحدًا في كل مرة ينجرف بنفس الطريقة، لأن كل ملف يبدأ دون معرفة المفاتيح التي صنعها الآخرون.
يقوم localize.dev بتسمية المفاتيح للتطبيق بأكمله في تشغيل واحد، ويتذكرها للتشغيل التالي. تغطي هذه المشاركة كيفية القيام بذلك.
من يسمي المفتاح
يقترح النموذج كل مفتاح من مسار الملف والمكون والسلسلة النصية. القواعد التي يحصل عليها قصيرة: مقاطع حالة الثعبان بأحرف صغيرة متصلة بنقاط، ومساحة اسم للميزة أو الشاشة، واسم لما تفعله السلسلة النصية، وليس ترجمة حرفية لها. src/components/AuthForm.tsx يعطي auth.*؛ يصبح العنوان auth.welcome_heading، وليس auth.welcome_back_we_missed_you.
كل شيء بعد ذلك هو رمز. يتم تنظيف كل مفتاح مقترح وتسجيله. إذا حصلت سلسلتان نصيتان مختلفتان على نفس الاسم، تحصل الثانية على لاحقة _2، ويتم إعادة تسمية مفتاح قد يتعارض مع فرع موجود في ملف اللغة حتى لا يتجاوز أي منهما الآخر.
نفس النص يحصل على نفس المفتاح
قبل إرسال سلسلة نصية إلى النموذج، يتحقق المحرك مما إذا كان هذا النص يحتوي بالفعل على مفتاح، إما في ملف اللغة المصدر الخاص بك أو من وقت سابق في نفس التشغيل. إذا كان الأمر كذلك، فإن الكود يستدعي هذا المفتاح مرة أخرى ولا يرى النموذج السلسلة النصية. يبلغ التشغيل عن هذه المفاتيح المعاد استخدامها، مع عد كل مكان يظهر فيه النص، لذا فإن عشرة أزرار "إلغاء" هي عشر عمليات إعادة استخدام لمفتاح واحد.
نصوص قصيرة تعني شيئين
إعادة الاستخدام حسب النص وحده خاطئة للنصوص القصيرة. "نشر" على زر هو فعل، وفي عنوان بطاقة هو اسم. تستخدم العديد من اللغات كلمات مختلفة لكل منهما.
نسخة من ثلاثة كلمات أو أقل، حتى 40 حرفًا، بدون عناصر أو علامات، تُفهم بجانب نصها: العنصر والخاصية التي توجد فيه، مثل button أو input[placeholder]. "نشر" على <button> و"نشر" في <h3> يصبحان رسالتين منفصلتين، ويتم إرسالهما مع تلميح عن مكان ظهورهما.
"placeholder" attribute on <input> in component <Login>
element text inside <button> in component <Composer>عندما تعود ترجمات المعنيين الاثنين متطابقة في كل لغة، يتم دمجهما مرة أخرى في مفتاح واحد. عندما تختلف، يبقى كلا المفتاحين. تحصل على مفتاح ثاني فقط حيث تحتاج إليه لغة فعلاً.
معرفة متى تغير النص المصدر
المفاتيح تساعد فقط إذا بقيت ترجماتها متماشية مع المصدر. عندما يغير شخص ما "حفظ" إلى "حفظ التغييرات" في en.json، تصبح كل ترجمات تلك المفتاح قديمة، لكن لا شيء في الملف يقول ذلك.
يسجل localize.lock.json بصمة لكل رسالة مصدر في وقت ترجمتها: أول 12 حرفًا سداسي عشري من SHA-256 الخاص بها. قم بارتكابه مع الكود الخاص بك. في التشغيل التالي، يتم ترجمة رسالة لم تعد بصمتها تتطابق، ويفشل localize-dev check في CI برسالة خطأ "ترجمات قديمة" التي تسمي المفاتيح.
مفاتيح في مجموعات أخرى
ليست كل المجموعات تستخدم المفاتيح المنقطة. تستخدم ملفات JSON الخاصة بـ Laravel وكتالوجات gettext النص المصدر كمفتاح، لذا يفعل ذلك localize.dev أيضًا. مفاتيح ARB في Flutter هي camelCase ومفاتيح Android هي snake_case، لأنها تتوقع ذلك أدواتهم.