Workflows

هناك مختلف سير العمل التي يمكن اعتمادها لتحسين عملية توليد الوثائق باستخدام JSquarto.

  1. توليد دوك
  2. توليد دوك مع نقل يدوي
  3. توليد Doc مع ترجمة crowdin

Doc generation

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

ستابس

  1. To do this, simply execute the JSquarto command with the desired custom CLI arguments, such as source and languages, to specify the source files directory and supported languages, respectively. على سبيل المثال:

    “`باش jsq doc:generate source=/path/to/your/source/files ```

توليد دوك مع ترجمة يدوية

من أجل الترجمة اليدوية للوثائق، يمكنك إنتاج الوثائق بلغات متعددة ثم ترجمة المحتوى يدوياً إلى اللغات المرغوبة. لسير العمل هذا، نستخدم babelquarto الذي يساعد على معاينة الوثائق بلغات متعددة. على الرغم من أن هذا لا يترجم المحتوى، فإنه يوفر معاينة للوثائق باللغات المحددة، مما يتيح لك ترجمة المحتوى يدوياً.

ستابس

  1. توليد الوثائق بلغات متعددة باستخدام JSquarto مع حجة “اللغات” لتحديد اللغات المعتمدة. على سبيل المثال:

    “باش jsq doc:generate languages=en,fr,es include_localized_versions source=/path/to/your/source/files ``` ملاحظة: تأكد من إدراج حجة 'include_localized_versions لإنتاج نسخ من الوثائق باللغات المحددة. إذا لم تكن مشمولة، سيتم إنشاء وثائق اللغة الافتراضية فقط. ولكن سيتم إضافة تكوين اللغات إلى ملف التكوين (_quarto.yml) فقط.

  2. ترجمة المحتوى يدويا في ملفات الوثائق التي تم إنشاؤها لكل لغة. يمكنك استخدام أدوات مثل ترجمة جوجل أو خدمات الترجمة المهنية لتسهيل عملية الترجمة.

  3. قم بتحميل RStudio وتثبيت حزمة ‘babelquarto’ من CRAN. يتم استخدام هذه الحزمة لمعاينة الوثائق بلغات متعددة. يمكنك تثبيت الحزمة باستخدام الأمر التالي:

    “`R install.packages(‘babelquarto’, repos = c(‘https://ropensci.r-universe.dev’, ‘https://cloud.r-project.org’)) ```

  4. افتح مجلد دوك الذي تم إنشاؤه في RStudio، انتقل إلى وحدة التحكم وتعيين دليل العمل إلى مجلد doc

    “`R project_dir <-”/home/richie/Desktop/repos/oscsa/JSquarto/docs” ```

  5. معاينة الوثائق بلغات متعددة باستخدام حزمة ‘babelquarto’. وعلى سبيل المثال، لتنفيذ الأمر التالي من أجل معاينة الوثائق باللغات الانكليزية والفرنسية والإسبانية:

    “`R babelquarto::render_book(file.path(parent_dir, project_dir)) ```

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

    “`باش jsq fix:all languages=en,fr,es ```

    ملاحظة: البرنامج النصي “إصلاح:all” هو برنامج نصي مخصص يصلح مشاكل التنقل في الوثائق المعاينة. يستخدم هذا البرنامج النصي لتحديث روابط التنقل في الوثائق المعاينة لتمكين التنقل السلس بين اللغات المختلفة. واللغات المحددة في النص ينبغي أن تتطابق مع اللغات المحددة في حجة “اللغات” أثناء عملية إعداد الوثائق.

  7. You can navigate to the docs/output/_book directory to view the previewed documentation in multiple languages. يمكنك من التحقق من الترجمات وضمان دقة وجودة الوثائق.

توليد دوك مع ترجمة الحشود

للترجمة الآلية للوثائق، يمكنك الاستفادة من منصة كرودن لتسهيل عملية الترجمة. كراودِن هو منصة إدارة الترجمة القائمة على السحابة والتي تمكنك من أتمتة ترجمة المحتوى إلى لغات متعددة. من خلال دمج كراودِن مع JSquarto، يمكنك تبسيط عملية الترجمة وإنشاء وثائق شاملة بلغات مختلفة بكفاءة.

ستابس

  1. توليد الوثائق بلغات متعددة باستخدام JSquarto مع حجة “اللغات” لتحديد اللغات المعتمدة. على سبيل المثال:

    “`باش jsq doc:generate languages=en,fr,es source=/path/to/your/source/files ```

    لاحظ أن حجة “include_localized_versions” ليست مطلوبة لسير العمل هذا، لأن كراودِن سوف يتعامل مع عملية الترجمة. وإنشاء ملفات مختلفة لكل لغة.

  2. دمج كراودِن مع JSquarto لأتمتة عملية الترجمة. لدمج كراودن، تحتاج إلى إنشاء مشروع كراودِن وتكوين إعدادات المشروع لتمكين الترجمة التلقائية للوثائق. You can refer to the Crowdin Github integration documentation for detailed instructions on setting up a project and configuring the translation settings
    في كراودين، يمكنك إعداد كيفية تسمية الملفات المترجمة، والتأكد من أنها تتبع تنسيق original_file_name.locale.extension على سبيل المثال index.en.qmd، index.fr.qmd، index.es.qmd

  3. بمجرد تكوين إعدادات مشروع Crowdin ، يمكنك المضي قدما في تقديم الوثائق بلغات متعددة باستخدام حزمة ‘babelquarto’. هذه الخطوة تمكنك من معاينة الوثائق بلغات مختلفة قبل بدء عملية الترجمة. يمكنك استخدام حزمة ‘babelquarto’ لمعاينة الوثائق بلغات متعددة، كما هو مبين في تدفق العمل السابق. للقيام بهذا فتح مجلد doc الذي تم إنشاؤه في RStudio، انتقل إلى وحدة التحكم وتعيين دليل العمل إلى مجلد doc

    “`R project_dir <-”path/to/your/project/output/folder” ```

    معاينة الوثائق بلغات متعددة باستخدام حزمة ‘babelquarto’. وعلى سبيل المثال، لتنفيذ الأمر التالي من أجل معاينة الوثائق باللغات الانكليزية والفرنسية والإسبانية:

    “`R babelquarto::render_book(file.path(parent_dir, project_dir)) ```

  4. After rendering the book, the html files will be generated and set in the docs/output/_book directory. يمكنك بعد ذلك خدمة الكتاب باستخدام أي خادم ثابت مثل ‘http-server’ أو ‘live-server’ لمعاينة الوثائق بلغات متعددة. بدلاً من ذلك، يمكنك تشغيل الأمر التالي لخدمة الكتاب:

    “`باش jsq serve ```

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

    “`باش jsq fix:all languages=en,fr,es ```

يستخدم سير العمل هذا JSquarto لتوليد الوثائق، و Crowdin لبدء عملية الترجمة التي تنشئ الملفات المترجمة باللغات المحددة، أخيرا حزمة ‘babelquarto’ لمعاينة الوثائق بلغات متعددة.