ترانسفورج: ترجمة موقع ثابت باستخدام نموذج لغوي كبير محلي، فقط الصفحات التي تغيرت

هذا الموقع متاح باللغة الإنجليزية بالإضافة إلى سبع لغات أخرى، ولم أقم بترجمة أي صفحة يدويًا قط. يؤدي TransForge هذه المهمة: إنه أداة سطر أوامر ترسل كل صفحة بصيغة Markdown إلى نموذج لغوي على خادم GPU الخاص بي، ثم تتحقق من النتيجة وتكتب ملف page.ja.md بجانب ملف page.md. ما يجعل هذا الأمر عمليًا هو نظام التتبع الذي يستخدمه البرنامج؛ فهو يحفظ بصمة لكل صفحة أصلية ولكل ترجمة تم إنشاؤها، لذا فإن التشغيل الليلي يترجم فقط ما تغير، ولا يتم الكتابة فوق أي ترجمة تم تصحيحها يدويًا.

ما النتيجة النهائية؟

أمر واحد فقط يخبرك بحالة كل لغة؛ هذا هو حال هذا الموقع بتاريخ 19 أكتوبر 2026 (43 صفحة باللغة الإنجليزية، وسبع لغات أخرى):

$ transforge status --site laserlloyd
site laserlloyd: 43 source pages x 7 languages | model mradermacher/Hy-MT2-30B-A3B-i1-GGUF/Hy-MT2-30B-A3B.i1-Q4_K_S
  lang     missing     stale    edited untracked     drift   current
  ja             1         0        10         0         0        32
  zh             1         0         8         0         0        34
  ...
  -> 7 sibling(s) need translation

لا يتصل أمر status بخادم النماذج اللغوية؛ بل يقرأ فقط الموقع والبيانات المسجلة. بعد ذلك، يقوم أمر transforge run --site laserlloyd بترجمة الصفحات السبع المفقودة فقط. يشير عمود "edited" إلى الصفحات التي تم تعديل ترجمتها يدويًا بعد إنشائها بواسطة TransForge؛ هذه الترجمات تبقى كما هي حتى أقرر غير ذلك.

كما يمكن للبرنامج ترجمة نصوص منفصلة، وهو ما يفيد في اختبار النماذج اللغوية بشكل سريع:

$ echo "Only the pages that changed get translated again." | transforge text --to ja
変更されたページのみ、再翻訳されます。

استغرقت هذه العملية 15 ثانية فقط، حيث كان النموذج اللغوي جاهزًا على خادم GPU.

كيف يقرر البرنامج ما يجب ترجمته؟

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

الحالة	المعنى	هل يقوم run بالترجمة؟
missing	لا يوجد ملف ترجمة بعد	نعم
stale	تغير المحتوى الإنجليزي الأصلي منذ آخر ترجمة	نعم
edited	تم تعديل الترجمة يدويًا	لا، إلا باستخدام --force وتحديد ملفات معينة عبر --files
untracked	يوجد ملف ترجمة لم ينشئه البرنامج أصلاً	لا؛ يمكن استخدام accept لاعتماده
drift	لم يتغير المحتوى الأصلي ولا الترجمة، لكن تغيرت إعدادات النموذج أو النص التوجيهي	لا؛ يُظهر البرنامج هذه الحالة فقط
current	لا حاجة للترجمة	لا

هناك خياران من هذه الخيارات لهما أهمية كبيرة: أي تعديل يدوي يتفوق على أي تغيير في المحتوى الأصلي؛ فإذا حدث كلاهما، تُصنف الصفحة كـ "edited"، وبالتالي لا تضيع التعديلات اليدوية أبدًا بسبب عمليات الترجمة الآلية. كما أن تغيير النموذج اللغوي لا يؤدي إلى إعادة ترجمة الموقع بأكمله دون علمك؛ بل يُظهر البرنامج حالة "drift" ليتيح لك تحديد الصفحات التي تستحق إعادة الترجمة.

قبل كتابة أي ترجمة، يقوم البرنامج بالتحقق من عدد العناوين والكتل البرمجية والجداول والصور والروابط؛ كما يتأكد من وجود اللغة المستهدفة فعليًا (مثل وجود حروف يابانية في صفحة يابانية)، وعدم إضافة أي مصطلحات تجارية محمية بشكل خاطئ، بالإضافة إلى التحقق من الحد الأدنى لطول النص. في حال فشل أي من هذه الاختبارات، تبقى الترجمة القديمة كما هي. أما الروابط الداخلية، فتُعدل بواسطة TransForge بعد إنهاء عملية الترجمة، وليس بواسطة النموذج اللغوي نفسه؛ مثلاً يتحول /projects/foo/ إلى /ja/projects/foo/ فقط إذا كان الملف الخاص باللغة اليابانية موجودًا. وأي ملف يتم الكتابة فوقه يُنسخ أولاً إلى مجلد احتياطي.

التثبيت والتشغيل الأول

uv tool install --python 3.13 git+https://github.com/LaserLloyd/TransForge
mkdir -p ~/.config/transforge
cat > ~/.config/transforge/config.toml <<'EOF'
[defaults]
endpoint = "http://localhost:1234"
model = "publisher/repo/file-stem"

[sites.example]
root = "~/sites/example"
content_dirs = ["content/projects", "content/pages"]
languages = ["ja", "de"]
lang_names = { ja = "Japanese", de = "German" }
link_dirs = ["projects"]
no_translate = ["MyProduct"]
translate_fields = ["title", "excerpt"]
EOF
export TRANSFORGE_LLM_API_KEY=...        # مطلوب فقط إذا كان الخادم يتطلب مفتاحًا
transforge config                         # عرض الإعدادات النهائية؛ يوضح مصدر المفتاح دون كشفه
transforge models                         # قائمة النماذج المتاحة على الخادم؛ انسخ المعرف الكامل في الإعدادات
transforge run --site example --dry-run   # عرض ما سيتم ترجمته فقط
transforge run --site example --limit 2   # ترجمة صفحتين فقط ثم مراجعتهما

يُشير endpoint إلى عنوان الخادم دون إضافة /v1، ويجب أن يكون model هو المعرف الكامل الذي يوفره الخادم (معرفات StudioForge تبدو كـ publisher/repo/file-stem)؛ أي معرف غير معروف يؤدي إلى خروج البرنامج برمز 5 مع عرض أقرب التطابقات الممكنة. يحتوي no_translate على الأسماء التي يجب أن تبقى كما هي، بينما يحدد translate_fields مفاتيح البيانات الوصفية التي يجب ترجمتها؛ جميع المفاتيح الأخرى تُنقل دون تغيير. على أنظمة Debian وUbuntu، لا يجب استخدام أمر pip install . مع بايثون النظام لأن ذلك ممنوع بموجب PEP 668؛ يمكن استخدام uv tool أو pipx أو بيئة افتراضية.

إذا كان موقعك يحتوي بالفعل على ترجمات تم إنشاؤها بطرق أخرى، فقم بتشغيل transforge accept --site example مرة واحدة؛ هذا يسجل الملفات الحالية كـ "current" ويمنع إعادة ترجمتها.

تُستخدم رموز الخروج للاستخدام في السكربتات وجدولة المهام: 0 يعني اكتمال العمل أو عدم وجود شيء يلزم الترجمة، و1 تشير إلى فشل ترجمة صفحة معينة (وفي حالة status تعني وجود عمل متبقي)، و2 تدل على خطأ في الإعدادات أو رفض الخادم لمفتاح الوصول، و4 تعني عدم توفر اتصال بالخادم، و5 تشير إلى عدم توافر النموذج المطلوب على الخادم، و6 تدل على وجود مهمة قياس أداء تستهلك موارد GPU مما يؤدي لتأجيل المهام الأخرى.

Docker

يتضمن المستودع أيضًا إعداد Compose يتيح تشغيل TransForge كأداة مساعدة ضد مجلد موقعك، مع تخزين البيانات المسجلة في وحدة تخزين منفصلة بالإضافة إلى خدمة جدولة اختيارية:

git clone https://github.com/LaserLloyd/TransForge.git && cd TransForge
cp deploy/compose/.env.example deploy/compose/.env    # قم بتعيين LLM_BASE_URL و TRANSFORGE_LLM_API_KEY
docker compose -f deploy/compose/compose.yml run --rm app status --all

لا يفتح البرنامج أي منافذ؛ داخل الحاوية، يُشير localhost إلى الحاوية نفسها، لذا يجب أن يستمع خادم النماذج اللغوية إلى عنوان يمكن للحاوية الوصول إليه. أنا أستخدم TransForge بشكل مباشر ولم أجرب الحاوية بنفسي؛ يتضمن المجلد docs/deploy/docker.md تفاصيل إضافية، بما في ذلك آلية النسخ الاحتياطي.

ما الجديد في الإصدار 0.2.0؟

صدر الإصدار 0.2.0 في أكتوبر 2026، وركز بشكل أساسي على التوافق مع خادم StudioForge 2.0 الذي يتطلب مفتاح وصول:

• دعم مفاتيح الوصول: يرسل TransForge رأس Authorization: Bearer في كل طلب إلى الخادم؛ ويقرأ المفتاح من متغير TRANSFORGE_LLM_API_KEY أو STUDIOFORGE_API_KEY أو أي متغير تحدده عبر api_key_env؛ تغيير المفتاح لا يؤدي لتصنيف أي صفحة كـ "stale". في حال غياب المفتاح وطلب الخادم وجوده، يُعرض رد نصي بسيط ويخرج البرنامج برمز 2 (يرد توضيح ذلك أدناه).
• التعامل الآمن مع مهام قياس الأداء: قبل بدء الترجمة، يتحقق البرنامج من وجود أي مهمة قياس أداء تستخدم GPU؛ وفي حال وجودها، يتوقف عن العمل. في الإصدارات السابقة، كان الفشل في الحصول على إذن استخدام يُفسر خطأً على أنه "لا توجد مهام جارية" مما يؤدي لتعطيل الحماية؛ أما الآن فالخروج يكون برمز 2.
• التوافق مع نظام ويندوز: يعمل البرنامج بكفاءة على ويندوز، وتستخدم الملفات المسجلة دائمًا شرطة مائلة / بغض النظر عن نظام التشغيل؛ هذا يسمح بنقلها بين ويندوز ولينكس والحاويات. يتم تحديث مفاتيح الملفات القديمة تلقائيًا عند القراءة. لا تقم بتشغيل accept --all لـ "إعادة بناء" الترجمات؛ فهذا سيصنف الترجمات القديمة كـ "current".
• إهمال رمز التحكم القديم: أصبح استخدام رمز التحكم اليدوي للتحميل والتفريغ غير ضروري؛ حيث يستخدم البرنامج مفتاح الوصول بدلاً منه. سيظل الرمز يعمل لإصدار واحد فقط، مع عرض تحذير عند استخدامه كمصدر وحيد للتحقق.

rig returned HTTP 401 Unauthorized for http://<server>:1234/api/status -- StudioForge requires credentials: set $TRANSFORGE_LLM_API_KEY (or `api_key_env` / `api_key` in the config)

للترقية، نفذ الأمر التالي: uv tool install --reinstall --python 3.13 git+https://github.com/LaserLloyd/TransForge، ثم حدد متغير TRANSFORGE_LLM_API_KEY إذا كان خادمك يتطلب مفتاح وصول.

تحذيرات هامة

• اقرأ أول بضعة ترجمات بنفسك: تقوم الاختبارات بالتحقق من سلامة الهيكل، لكنها لا تكتشف الأخطاء اللغوية. أنا أستخدم نموذج Hy-MT2 30B مع إعداد prompt_template = "hunyuan-mt" (النص التوجيهي المختصر الذي تتطلبه نماذج الترجمة البحتة)؛ أي نموذج تعليمي عام يعمل مع القالب الافتراضي. ومع ذلك، فإن كل محتوى مهم يستحق مراجعة بشرية.
• الترجمات التي تم تحريرها تظل كما هي حتى قرارك: هذا هو الغرض منه، لكنه يعني أيضًا أن أي تعديل في المحتوى الأصلي لن يصل إلى تلك اللغات؛ يمكن استخدام status -v لعرض هذه الصفحات، بينما يُستخدم run --force --files <page> لإعادة ترجمة صفحة معينة عمدًا.
• تغيير النموذج اللغوي لا يعيد الترجمة تلقائيًا: بدلاً من ذلك، تظهر حالة "drift" لكل الصفحات؛ لتصحيح ذلك، يجب تحديد الصفحات المطلوبة باستخدام --force --files.
• البرنامج مخصص لـ StudioForge: تستخدم عمليات التحميل المسبق للنموذج وإجراءات قياس الأداء واجهة برمجة خاصة بـ StudioForge. يذكر ملف README أن خادم llama.cpp يمكن استخدامه أيضًا، لكن تجربتي اقتصرت على StudioForge فقط.
• لا يدعم الترجمة التكرارية: يتم فحص المجلدات المحددة في content_dirs على مستوى واحد فقط؛ لذا يجب سرد كل مجلد يحتوي على صفحات بشكل منفصل.
• الصفحات التي يجب أن تبقى باللغة الإنجليزية: يمكن تحقيق ذلك بإضافة en_only: true (أو translate: false) في البيانات الوصفية للصفحة، مما يؤدي لتخطيها تمامًا من عملية الترجمة.

كيفية الحصول عليه؟

github.com/LaserLloyd/TransForge، متاح تحت رخصة MIT. يتضمن ملف README تعليمات تثبيت لويندوز ولينكس وماك أو إس، بالإضافة إلى مرجع كامل للإعدادات ومرحلة مراجعة اختيارية يمكنها استخدام نماذج سحابية (غير مفعلة افتراضيًا؛ الترجمة تتم دائمًا محليًا).

مرتبط: StudioForge (خادم GPU الذي يعمل عليه النموذج)، إدارة مواقعي باستخدام صندوق ذكاء اصطناعي محلي، وكيفية جعل النموذج اللغوي يعدل أي مشروع ليتناسب مع نظامك.