=encoding utf-8

=head1 NAME

App::Greple::xlate - وحدة دعم الترجمة لأداة greple

=head1 SYNOPSIS

    greple -Mxlate::deepl --xlate pattern target-file

    greple -Mxlate::gpt4 --xlate pattern target-file

    greple -Mxlate::gpt5 --xlate pattern target-file

    greple -Mxlate --xlate-engine gpt5 --xlate pattern target-file

=head1 VERSION

Version 0.9918

=head1 DESCRIPTION

B<Greple> B<xlate> تعثر الوحدة على كتل النص المطلوبة وتستبدلها بالنص المُترجَم. حاليًا تم تنفيذ وحدات DeepL (F<deepl.pm>)، وChatGPT 4.1 (F<gpt4.pm>)، وGPT-5 (F<gpt5.pm>) كمحرّكات خلفية.

إذا كنت تريد ترجمة كتل نصية عادية في مستند مكتوب بأسلوب POD الخاص بلغة Perl، فاستخدم أمر B<greple> مع الوحدة C<xlate::deepl> وC<perl> بهذا الشكل:

    greple -Mxlate::deepl -Mperl --pod --re '^([\w\pP].*\n)+' --all foo.pm

في هذا الأمر، تعني سلسلة النمط C<^([\w\pP].*\n)+> أسطرًا متتالية تبدأ بحروف وأرقام وعلامات ترقيم. يعرض هذا الأمر المنطقة المراد ترجمتها مميّزة. يُستخدم الخيار B<--all> لإنتاج النص الكامل.

=for html <p>
<img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/select-area.png">
</p>

ثم أضف الخيار C<--xlate> لترجمة المنطقة المحددة. عندها سيعثر على الأقسام المطلوبة ويستبدلها بمخرجات أمر B<deepl>.

افتراضيًا، يُطبع النص الأصلي والمُترجَم بصيغة "علامات التعارض" المتوافقة مع L<git(1)>. باستخدام صيغة C<ifdef> يمكنك الحصول على الجزء المطلوب بواسطة أمر L<unifdef(1)> بسهولة. يمكن تحديد تنسيق الإخراج عبر الخيار B<--xlate-format>.

=for html <p>
<img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/format-conflict.png">
</p>

إذا كنت تريد ترجمة النص بالكامل، فاستخدم الخيار B<--match-all>. هذا اختصار لتحديد النمط C<(?s).+> الذي يطابق النص بأكمله.

يمكن عرض بيانات تنسيق علامات التعارض بأسلوب جنبًا إلى جنب بواسطة أمر L<sdif|App::sdif> مع الخيار C<-V>. ولأنه لا معنى للمقارنة على أساس كل سطر على حدة، يُنصح بالخيار C<--no-cdif>. إذا لم تكن بحاجة إلى تلوين النص، فحدّد C<--no-textcolor> (أو C<--no-tc>).

    sdif -V --no-filename --no-tc --no-cdif data_shishin.deepl-EN-US.cm

=for html <p>
<img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/sdif-cm-view.png">
</p>

=head1 NORMALIZATION

تُجرى المعالجة بوحدات محددة، ولكن في حالة تسلسل من عدة أسطر من نص غير فارغ، تُحوَّل معًا إلى سطر واحد. تُنفَّذ هذه العملية على النحو التالي:

=over 2

=item *

أزل المسافات البيضاء من بداية ونهاية كل سطر.

=item *

إذا انتهى السطر بعلامة ترقيم بعرض كامل، فادمجه مع السطر التالي.

=item *

إذا انتهى السطر بمحرف بعرض كامل وبدأ السطر التالي بمحرف بعرض كامل، فادمج السطرين.

=item *

إذا لم يكن أحد طرفي السطر (النهاية أو البداية) محرفًا بعرض كامل، فادمجهما بإدراج مسافة.

=back

تُدار بيانات التخزين المؤقت بناءً على النص المُطَبَّع، لذا حتى إذا أُجريت تعديلات لا تؤثر في نتائج التطبيع، ستظل بيانات الترجمة المخبأة فعّالة.

تُجرى عملية التطبيع فقط للنمط الأول (ذي الفهرس 0) والأنماط ذات الأرقام الزوجية. لذلك، إذا تم تحديد نمطين كما يلي، فسيُعالَج النص المطابق للنمط الأول بعد التطبيع، ولن تُجرى أي عملية تطبيع على النص المطابق للنمط الثاني.

    greple -Mxlate -E normalized -E not-normalized

لذا استخدم النمط الأول للنص الذي سيُعالَج بضمّ عدة أسطر إلى سطر واحد، واستخدم النمط الثاني للنص مُسبق التنسيق. إذا لم يكن هناك نص يطابق النمط الأول، فاستخدم نمطًا لا يطابق أي شيء مثل C<(?!)>.

=head1 MASKING

أحيانًا توجد أجزاء من النص لا تريد ترجمتها. على سبيل المثال، الوسوم في ملفات Markdown. تقترح DeepL في مثل هذه الحالات تحويل الجزء المراد استثناؤه إلى وسوم XML، ثم ترجمته، ثم استعادته بعد اكتمال الترجمة. لدعم ذلك، يمكن تحديد الأجزاء التي سيتم حجبها من الترجمة.

    --xlate-setopt maskfile=MASKPATTERN

سيفسر كل سطر من الملف `MASKPATTERN` كتع表达 نمطي (regular expression)، تُترجم السلاسل المطابقة له، ثم تُعاد إلى حالتها بعد المعالجة. تُتجاهل الأسطر التي تبدأ بـ C<#>.

يمكن كتابة نمط معقد على عدة أسطر مع إخفاء سطر جديد بواسطة الشرطة المائلة العكسية.

يمكن رؤية كيفية تحويل النص بواسطة الحجب عبر خيار B<--xlate-mask>.

هذا الواجهة تجريبية وقابلة للتغيير في المستقبل.

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

=item B<--xlate-fold-width>=I<n> (Default: 70)

تفعيل عملية الترجمة لكل منطقة مطابقة.

بدون هذا الخيار، يتصرف B<greple> كأمر بحث عادي. لذا يمكنك التحقق من أي جزء من الملف سيكون موضوعًا للترجمة قبل تنفيذ العمل الفعلي.

تذهب نتيجة الأمر إلى المخرج القياسي، لذا أعد توجيهها إلى ملف عند الحاجة، أو فكر في استخدام وحدة L<App::Greple::update>.

الخيار B<--xlate> يستدعي خيار B<--xlate-color> مع خيار B<--color=never>.

مع خيار B<--xlate-fold>، يُطوى النص المحول بعرض محدد. العرض الافتراضي 70 ويمكن تعيينه بواسطة خيار B<--xlate-fold-width>. تُحجز أربع أعمدة لعملية الإدراج، لذا يمكن لكل سطر أن يحمل حتى 74 حرفًا كحد أقصى.

=item B<--xlate-engine>=I<engine>

يحدد محرك الترجمة المراد استخدامه. إذا حددت وحدة المحرك مباشرة مثل C<-Mxlate::deepl>، فلست بحاجة لاستخدام هذا الخيار.

في هذا الوقت، المحركات التالية متاحة

=over 2

=item * B<deepl>: DeepL API

=item * B<gpt3>: gpt-3.5-turbo

=item * B<gpt4>: gpt-4.1

=item * B<gpt4o>: gpt-4o-mini

واجهة B<gpt-4o> غير مستقرة ولا يمكن ضمان عملها بشكل صحيح في الوقت الحالي.

=item * B<gpt5>: gpt-5

=back

=item B<--xlate-labor>

=item B<--xlabor>

بدلاً من استدعاء محرك الترجمة، يُتوقع أن تقوم بالعمل يدويًا. بعد تحضير النص المراد ترجمته، تُنسخ إلى الحافظة. يُتوقع منك لصقها في النموذج، نسخ النتيجة إلى الحافظة، ثم الضغط على Enter.

=item B<--xlate-to> (Default: C<EN-US>)

حدد اللغة الهدف. يمكنك الحصول على اللغات المتاحة بواسطة أمر C<deepl languages> عند استخدام محرك B<DeepL>.

=item B<--xlate-format>=I<format> (Default: C<conflict>)

حدد تنسيق الإخراج للنص الأصلي والمترجم.

تفترض التنسيقات التالية غير C<xtxt> أن الجزء المراد ترجمته عبارة عن مجموعة من الأسطر. في الواقع، من الممكن ترجمة جزء فقط من السطر، لكن تحديد تنسيق غير C<xtxt> لن ينتج نتائج ذات معنى.

=over 4

=item B<conflict>, B<cm>

يُطبع النص الأصلي والنص المحول بتنسيق علامات تعارض L<git(1)>.

    <<<<<<< ORIGINAL
    original text
    =======
    translated Japanese text
    >>>>>>> JA

يمكنك استعادة الملف الأصلي بالأمر التالي L<sed(1)>.

    sed -e '/^<<<<<<< /d' -e '/^=======$/,/^>>>>>>> /d'

=item B<colon>, I<:::::::>

يُخرَج النص الأصلي والنص المترجم بأسلوب الحاوية المخصصة في Markdown.

    ::::::: ORIGINAL
    original text
    :::::::
    ::::::: JA
    translated Japanese text
    :::::::

سيُترجم النص أعلاه إلى ما يلي في HTML.

    <div class="ORIGINAL">
    original text
    </div>
    <div class="JA">
    translated Japanese text
    </div>

عدد النقطتين الرأسيتين هو 7 افتراضيًا. إذا حددت تسلسل نقطتين مثل C<:::::>، فسيُستخدم بدلًا من 7 نقطتين.

=item B<ifdef>

يُطبع النص الأصلي والمحّول بتنسيق L<cpp(1)> C<#ifdef>.

    #ifdef ORIGINAL
    original text
    #endif
    #ifdef JA
    translated Japanese text
    #endif

يمكنك جلب النص الياباني فقط بواسطة الأمر B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

يتم طباعة النص الأصلي والمحَوَّل مفصولين بسطر فارغ واحد. بالنسبة إلى C<space+>، يتم أيضًا إخراج سطر جديد بعد النص المحوَّل.

=item B<xtxt>

إذا كان التنسيق C<xtxt> (النص المترجم) أو غير معروف، فسيتم طباعة النص المترجم فقط.

=back

=item B<--xlate-maxlen>=I<chars> (Default: 0)

حدد الحد الأقصى لطول النص الذي سيتم إرساله إلى واجهة برمجة التطبيقات مرة واحدة. القيمة الافتراضية مضبوطة كما في خدمة حساب DeepL المجانية: 128K لواجهة برمجة التطبيقات (B<--xlate>) و5000 لواجهة الحافظة (B<--xlate-labor>). قد تتمكن من تغيير هذه القيم إذا كنت تستخدم خدمة Pro.

=item B<--xlate-maxline>=I<n> (Default: 0)

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

عيّن هذه القيمة إلى 1 إذا كنت تريد ترجمة سطر واحد في كل مرة. لهذا الخيار أولوية على خيار C<--xlate-maxlen>.

=item B<--xlate-prompt>=I<text>

حدد موجهًا مخصصًا ليُرسل إلى محرك الترجمة. هذا الخيار متاح فقط عند استخدام محركات ChatGPT (gpt3 وgpt4 وgpt4o). يمكنك تخصيص سلوك الترجمة بتقديم تعليمات محددة لنموذج الذكاء الاصطناعي. إذا كان الموجه يحتوي على C<%s>، فسيتم استبداله باسم اللغة المستهدفة.

=item B<--xlate-context>=I<text>

حدد معلومات سياقية إضافية تُرسل إلى محرك الترجمة. يمكن استخدام هذا الخيار عدة مرات لتقديم عدة سلاسل سياقية. تساعد المعلومات السياقية محرك الترجمة على فهم الخلفية وإنتاج ترجمات أكثر دقة.

=item B<--xlate-glossary>=I<glossary>

حدد معرّف مسرد لاستخدامه في الترجمة. هذا الخيار متاح فقط عند استخدام محرك DeepL. يجب الحصول على معرّف المسرد من حساب DeepL لديك ويضمن ترجمة متسقة للمصطلحات المحددة.

=item B<-->[B<no->]B<xlate-progress> (Default: True)

اعرض نتيجة الترجمة في الوقت الحقيقي في مخرجات STDERR.

=item B<--xlate-stripe>

استخدم وحدة L<App::Greple::stripe> لإظهار الجزء المطابق بأسلوب التظليل المخطط (zebra striping). يكون هذا مفيدًا عندما تكون الأجزاء المتطابقة متصلة على التوالي.

يتم تبديل لوحة الألوان وفقًا للون خلفية الطرفية. إذا أردت التحديد صراحة، يمكنك استخدام B<--xlate-stripe-light> أو B<--xlate-stripe-dark>.

=item B<--xlate-mask>

نفّذ وظيفة الإخفاء واعرض النص المحوَّل كما هو دون استرجاع.

=item B<--match-all>

عيّن كامل نص الملف كمنطقة هدف.

=item B<--lineify-cm>

=item B<--lineify-colon>

في حالتي تنسيقي C<cm> وC<colon>، يتم تقسيم الإخراج وتنسيقه سطرًا بسطر. لذلك، إذا كان من المقرر ترجمة جزء فقط من سطر، فلن يمكن الحصول على النتيجة المتوقعة. تعمل هذه المرشحات على إصلاح الإخراج الذي فسد بسبب ترجمة جزء من السطر إلى إخراج طبيعي سطرًا بسطر.

في التنفيذ الحالي، إذا تُرجمت أجزاء متعددة من سطر واحد، يتم إخراجها كسطور مستقلة.

=back

=head1 CACHE OPTIONS

يمكن لوحدة B<xlate> تخزين نص مترجم مؤقتًا لكل ملف وقراءته قبل التنفيذ لإزالة كلفة الاستعلام من الخادم. باستخدام استراتيجية التخزين المؤقت الافتراضية C<auto>، تتم المحافظة على بيانات التخزين المؤقت فقط عندما يوجد ملف التخزين المؤقت للملف الهدف.

استخدم B<--xlate-cache=clear> لبدء إدارة التخزين المؤقت أو لتنظيف جميع بيانات التخزين المؤقت الموجودة. بعد التنفيذ بهذا الخيار، سيتم إنشاء ملف تخزين مؤقت جديد إن لم يكن موجودًا ثم تتم صيانته تلقائيًا بعد ذلك.

=over 7

=item --xlate-cache=I<strategy>

=over 4

=item C<auto> (Default)

حافظ على ملف التخزين المؤقت إذا كان موجودًا.

=item C<create>

أنشئ ملف تخزين مؤقت فارغًا ثم اخرج.

=item C<always>, C<yes>, C<1>

حافظ على ذاكرة التخزين المؤقت على أي حال طالما أن الهدف ملف عادي.

=item C<clear>

امسح بيانات ذاكرة التخزين المؤقت أولاً.

=item C<never>, C<no>, C<0>

لا تستخدم ملف ذاكرة التخزين المؤقت مطلقًا حتى إذا كان موجودًا.

=item C<accumulate>

وفقًا للسلوك الافتراضي، تتم إزالة البيانات غير المستخدمة من ملف ذاكرة التخزين المؤقت. إذا كنت لا تريد إزالتها وتريد الاحتفاظ بها في الملف، استخدم C<accumulate>.

=back

=item B<--xlate-update>

يفرض هذا الخيار تحديث ملف ذاكرة التخزين المؤقت حتى إذا لم يكن ذلك ضروريًا.

=back

=head1 COMMAND LINE INTERFACE

يمكنك استخدام هذه الوحدة بسهولة من سطر الأوامر باستخدام أمر C<xlate> المُضمَّن في التوزيعة. راجع صفحة الدليل C<xlate> للاستخدام.

يدعم الأمر C<xlate> خيارات طويلة بأسلوب GNU مثل C<--to-lang> وC<--from-lang> وC<--engine> وC<--file>. استخدم C<xlate -h> لرؤية جميع الخيارات المتاحة.

يعمل أمر C<xlate> بالتنسيق مع بيئة Docker، لذا حتى إذا لم يكن لديك أي شيء مُثبّت محليًا، يمكنك استخدامه طالما أن Docker متاح. استخدم خيار C<-D> أو C<-C>.

تتم إدارة عمليات Docker بواسطة البرنامج النصي C<xrun>، والذي يمكن استخدامه أيضًا كأمر مستقل. يدعم البرنامج النصي C<xrun> ملف التهيئة C<.xrunrc> لإعدادات الحاوية الدائمة.

أيضًا، نظرًا لتوفّر ملفات make لأنماط مستندات متنوعة، فإن الترجمة إلى لغات أخرى ممكنة دون مواصفات خاصة. استخدم خيار C<-M>.

يمكنك أيضًا الجمع بين خياري Docker وC<make> بحيث يمكنك تشغيل C<make> في بيئة Docker.

التشغيل مثل C<xlate -C> سيؤدي إلى إطلاق صدفة مع ربط مستودع git العامل الحالي.

اقرأ المقال الياباني في قسم L</SEE ALSO> للتفاصيل.

=head1 EMACS

حمّل ملف F<xlate.el> المُضمَّن في المستودع لاستخدام أمر C<xlate> من محرر Emacs. تقوم دالة C<xlate-region> بترجمة المنطقة المحددة. اللغة الافتراضية هي C<EN-US> ويمكنك تحديد اللغة عند استدعائها مع معامل بادئة.

=for html <p>
<img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/emacs.png">
</p>

=head1 ENVIRONMENT

=over 7

=item DEEPL_AUTH_KEY

عيّن مفتاح المصادقة لخدمة DeepL.

=item OPENAI_API_KEY

مفتاح مصادقة OpenAI.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

عليك تثبيت أدوات سطر الأوامر لكل من DeepL وChatGPT.

L<https://github.com/DeepLcom/deepl-python>

L<https://github.com/tecolicom/App-gpty>

=head1 SEE ALSO

L<App::Greple::xlate>

L<App::Greple::xlate::deepl>

L<App::Greple::xlate::gpt4>

L<App::Greple::xlate::gpt5>

=over 2

=item * L<https://hub.docker.com/r/tecolicom/xlate>

صورة حاوية Docker.

=item * L<https://github.com/tecolicom/getoptlong>

تُستخدم مكتبة C<getoptlong.sh> لتحليل الخيارات في البرنامجين النصيين C<xlate> وC<xrun>.

=item * L<https://github.com/DeepLcom/deepl-python>

مكتبة DeepL لبايثون وأمر CLI.

=item * L<https://github.com/openai/openai-python>

مكتبة OpenAI لبايثون

=item * L<https://github.com/tecolicom/App-gpty>

واجهة سطر الأوامر لـ OpenAI

=item * L<App::Greple>

راجع دليل B<greple> للتفاصيل حول نمط نص الهدف. استخدم الخيارات B<--inside> وB<--outside> وB<--include> وB<--exclude> لتقييد منطقة المطابقة.

=item * L<App::Greple::update>

يمكنك استخدام وحدة C<-Mupdate> لتعديل الملفات بنتيجة أمر B<greple>.

=item * L<App::sdif>

استخدم B<sdif> لإظهار تنسيق علامات التعارض جنبًا إلى جنب مع خيار B<-V>.

=item * L<App::Greple::stripe>

تُستخدم وحدة Greple B<stripe> بواسطة خيار B<--xlate-stripe>.

=back

=head2 ARTICLES

=over 2

=item * L<https://qiita.com/kaz-utashiro/items/1c1a51a4591922e18250>

وحدة Greple للترجمة والاستبدال للأجزاء الضرورية فقط باستخدام واجهة DeepL API (باللغة اليابانية)

=item * L<https://qiita.com/kaz-utashiro/items/a5e19736416ca183ecf6>

إنشاء مستندات بـ 15 لغة باستخدام وحدة DeepL API (باللغة اليابانية)

=item * L<https://qiita.com/kaz-utashiro/items/1b9e155d6ae0620ab4dd>

بيئة Docker للترجمة الآلية باستخدام DeepL API (باللغة اليابانية)

=back

=head1 AUTHOR

Kazumasa Utashiro

=head1 LICENSE

Copyright © 2023-2025 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut
