# NAME

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

# SYNOPSIS

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

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

# VERSION

Version 2.01

# DESCRIPTION

**Greple** **xlate** تعثر الوحدة على كتل النص المطلوبة وتستبدلها بالنص المترجم. المحرك الأساسي هو GPT-5.5 (`llm/gpt5.pm`)، والذي يستدعي الأمر [llm](https://llm.datasette.io/)؛ كما يتم تضمين DeepL (`deepl.pm`) والمحركات القديمة المستندة إلى **gpty**.

تُخزَّن الترجمات مؤقتًا لكل ملف، لذا فإن إعادة تشغيل الأمر لا تكلّف شيئًا للنص غير المتغيّر. عند تحرير مستند، تُرسل الفقرات التي تغيّرت فقط إلى واجهة API مرة أخرى؛ ويتلقى المحرك الواعي بالسياق أيضًا الترجمات المحيطة، ونص المصدر الخام حول التغيير، والإصدار السابق من الفقرة المحررة، بحيث تحافظ الترجمة الجديدة على الصياغة المعتمدة (انظر **--xlate-context-window**). يمكن إخفاء السلاسل الحساسة قبل الإرسال (انظر ["ANONYMIZATION AND TEMPLATES"](#anonymization-and-templates)).

إذا كنت تريد ترجمة كتل نصية عادية في مستند مكتوب بأسلوب pod الخاص بـ Perl، فاستخدم أمر **greple** مع `--xlate-engine gpt5` ووحدة `perl` كما يلي:

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

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

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

ثم أضف الخيار `--xlate` لترجمة المنطقة المحددة. عندها سيعثر على الأقسام المطلوبة ويستبدلها بمخرجات محرك الترجمة.

افتراضيًا، يُطبع النص الأصلي والمُترجَم بصيغة "علامات التعارض" المتوافقة مع [git(1)](http://man.he.net/man1/git). باستخدام صيغة `ifdef` يمكنك الحصول على الجزء المطلوب بواسطة أمر [unifdef(1)](http://man.he.net/man1/unifdef) بسهولة. يمكن تحديد تنسيق الإخراج عبر الخيار **--xlate-format**.

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

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

يمكن عرض بيانات تنسيق علامات التعارض بأسلوب جنبًا إلى جنب بواسطة أمر [sdif](https://metacpan.org/pod/App%3A%3Asdif) مع الخيار `-V`. ولأنه لا معنى للمقارنة على أساس كل سطر على حدة، يُنصح بالخيار `--no-cdif`. إذا لم تكن بحاجة إلى تلوين النص، فحدّد `--no-textcolor` (أو `--no-tc`).

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

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

# NORMALIZATION

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

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

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

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

    greple -Mxlate -E normalized -E not-normalized

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

# MASKING

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

    --xlate-setopt maskfile=MASKPATTERN

سيتم تفسير كل سطر من الملف `MASKPATTERN` كتعبير منتظم، وترجمة السلاسل المطابقة له، ثم الرجوع عن التغييرات بعد المعالجة. يتم تجاهل الأسطر التي تبدأ بـ `#`.

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

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

يحمي الحجب العلامات من الترجمة. لإخفاء السلاسل الحساسة عن خدمة الترجمة نفسها، راجع ["ANONYMIZATION AND TEMPLATES"](#anonymization-and-templates)؛ ويمكن استخدامهما معًا.

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

# ANONYMIZATION AND TEMPLATES

يمكن إخفاء السلاسل الحساسة قبل إرسالها إلى واجهة API للترجمة ثم استعادتها في المخرجات. تتوفر ثلاثة مصادر لقواعد إخفاء الهوية: ملف قاموس (**--xlate-anonymize**)، وعلامات مضمنة في المستند نفسه (**--xlate-anonymize-mark**)، وقيم YAML front matter (**--xlate-frontmatter**). تُستبدل كل سلسلة بوسم فئة مثل `<person id=1 />` أثناء الإرسال. هدف الإخفاء هو إرسال واجهة API فقط: تخزن ملفات التخزين المؤقت المحلية النص العادي المستعاد. استخدم **--xlate-dryrun** لفحص ما سيُرسل بالضبط.

بالنسبة إلى مستندات النماذج (التقارير الفصلية وما شابه)، عرّف الأطراف الفاعلة مسبقًا وأشر إليها في المتن:

    ---
    報告者: 山田太郎
    発注会社: アクメ株式会社
    ---
    本件について {{ 報告者 }} が調査を行った。

ترجم القالب مرة واحدة لكل لغة باستخدام `--xlate-template` (و`--xlate-frontmatter` عندما تُحفظ القيم في الملف)، ثم اعرض كل حالة باستخدام وضع **pandoc-embedz** المستقل -- القيم الموجودة تحت `global:` في تهيئة خارجية لا تصل إلى واجهة API للترجمة إطلاقًا:

    greple -Mxlate --xlate --xlate-engine=gpt5 --xlate-to=EN-US \
           --xlate-template= --xlate-format=xtxt \
           --match-paragraph --all --need=0 \
           report-template.md > report-template.EN.md
    pandoc-embedz --standalone report-template.EN.md \
                  -c case-123.yaml -o report-123.EN.md < /dev/null

بالنسبة إلى العلامات المضمنة، فإن توفير تهيئة تعريف ماكرو يجعل القالب المترجم نفسه يعرض إما الأسماء الحقيقية أو نسخة منقحة:

    # macros.yaml           # macros-redacted.yaml
    preamble: |             preamble: |
      {% macro person(name) %}{{ name }}{% endmacro %}
                              {% macro person(name) %}(関係者){% endmacro %}

استبعد كتل embedz من الترجمة عندما يحتويها المستند:

    --exclude '^```embedz\n(?s:.*?)^```\n'

# OPTIONS

- **--xlate**
- **--xlate-color**
- **--xlate-fold**
- **--xlate-fold-width**=_n_ (Default: 70)

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

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

    تذهب نتيجة الأمر إلى المخرج القياسي، لذا أعد توجيهها إلى ملف عند الحاجة، أو فكر في استخدام وحدة [App::Greple::update](https://metacpan.org/pod/App%3A%3AGreple%3A%3Aupdate).

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

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

- **--xlate-engine**=_engine_

    يحدد محرك الترجمة المراد استخدامه.

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

    - **gpt5**: gpt-5.5 (via the `llm` command)
    - **deepl**: DeepL API (via the `deepl` command)
    - **gpt3**: gpt-3.5-turbo (legacy, via the `gpty` command)
    - **gpt4o**: gpt-4o-mini (legacy, via the `gpty` command)

    تُبحث وحدات المحرك أولاً في مساحات أسماء الواجهة الخلفية (`llm`، ثم `gpty`)، ثم مباشرةً تحت `App::Greple::xlate`. لذلك يحمّل `gpt5` الوحدة `App::Greple::xlate::llm::gpt5` التي تستدعي الأمر `llm`، بينما يعود `gpt4o` إلى `App::Greple::xlate::gpty::gpt4o`. استخدم `--xlate-setopt backend=gpty` لفرض واجهة خلفية محددة.

- **--xlate-labor**
- **--xlabor**

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

- **--xlate-to** (Default: `EN-US`)

    حدد اللغة الهدف. تقبل محركات LLM أي اسم لغة أو رمز يفهمه النموذج؛ ويُدرج ذلك في موجّه الترجمة. يمكنك الحصول على اللغات المتاحة بواسطة أمر `deepl languages` عند استخدام محرك **DeepL**.

- **--xlate-from** (Default: `ORIGINAL`)

    التسمية المستخدمة للنص الأصلي في تنسيقات الإخراج `conflict` و`colon` و`ifdef`. مع محرك **DeepL**، تُمرَّر القيمة غير الافتراضية أيضًا كلغة المصدر.

- **--xlate-format**=_format_ (Default: `conflict`)

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

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

    - **conflict**, **cm**

        يُطبع النص الأصلي والنص المحول بتنسيق علامات تعارض [git(1)](http://man.he.net/man1/git).

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

        يمكنك استعادة الملف الأصلي بالأمر التالي [sed(1)](http://man.he.net/man1/sed).

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

    - **colon**, _:::::::_

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

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

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

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

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

    - **ifdef**

        يُطبع النص الأصلي والمحّول بتنسيق [cpp(1)](http://man.he.net/man1/cpp) `#ifdef`.

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

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

            unifdef -UORIGINAL -DJA foo.ja.pm

    - **space**
    - **space+**

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

    - **xtxt**

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

- **--xlate-maxlen**=_chars_ (Default: 0)

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

- **--xlate-maxline**=_n_ (Default: 0)

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

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

- **--xlate-prompt**=_text_

    حدّد موجّهًا مخصصًا ليتم إرساله إلى محرك الترجمة. يتوفر هذا الخيار لمحركات LLM (`gpt3`، `gpt4o`، `gpt5`) لكنه لا يتوفر لـ DeepL. يمكنك تخصيص سلوك الترجمة من خلال تقديم تعليمات محددة إلى نموذج الذكاء الاصطناعي. إذا كان الموجّه يحتوي على `%s`، فسيُستبدل باسم اللغة الهدف.

- **--xlate-context**=_text_

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

- **--xlate-context-window**=_n_

    (Context-aware engines only, e.g. `gpt5` on the llm backend)
    عدد الكتل المترجمة المحيطة التي تُمرَّر كسياق مرجعي عند إعادة ترجمة الكتل المتغيرة (الافتراضي 2). يتضمن السياق أيضًا نص المصدر الخام حول المنطقة المتغيرة (العناوين، بنية القوائم، التعليقات التوضيحية)، وعند توفره، الإصدار السابق من النص المتغير المستعاد من ذاكرة التخزين المؤقت، بحيث تُحفظ الصياغة غير المتغيرة. اضبطه على 0 لتعطيل الترجمة الواعية بالسياق بالكامل. لاحظ أن كل منطقة متغيرة تُترجم في استدعاء API خاص بها، ويمكن للسياق أن يضيف ما يصل إلى نحو 8000 محرف إلى موجّه النظام، لذلك تستبدل الترجمة الواعية بالسياق بعض التكلفة الإضافية بالاتساق.

- **--xlate-cache-seed**=_file_

    هيّئ ذاكرة التخزين المؤقت لمستند جديد من ملف ذاكرة التخزين المؤقت لمستند آخر. مفيد للتقارير الدورية: زوّد ذاكرة التخزين المؤقت للإصدار الجديد بذاكرة الإصدار السابق، حتى لا تُعاد ترجمة الفقرات غير المتغيرة وتحتفظ الفقرات المحررة بصياغة الإصدار السابق. لا تُستخدم البذرة إلا عندما تكون ذاكرة التخزين المؤقت الهدف فارغة؛ وإلا فتُتجاهل مع تحذير. مع `--xlate-cache=auto` الافتراضي، فإن تحديد بذرة يعني أيضًا إنشاء ملف ذاكرة التخزين المؤقت للمستند الجديد.

- **--xlate-anonymize**=_file_

    أخفِ هوية السلاسل الحساسة قبل إرسالها إلى API الترجمة، واستعدها في المخرجات. يعطي ملف القاموس إدخالًا واحدًا لكل عنصر: بصيغة JSON (قياسية، قابلة للتوليد آليًا)

        [ { "category": "person",  "text": "山田太郎" },
          { "category": "company", "regex": "アクメ(株式会社)?" } ]

    أو بتنسيق أسطر بسيط (`category pattern`، `/.../` للتعبير النمطي). يُستبدل كل عنصر بوسم فئة مثل `<person id=1 />`؛ وتحصل السلسلة نفسها دائمًا على الوسم نفسه، بحيث يمكن للنموذج تتبع من هو من. تُتجاهل حقول JSON غير المعروفة، لذا يمكن للمولّدات (مثل LLM محلي يستخرج الكيانات) إضافة تعليقاتها التوضيحية الخاصة. الفئة `lit` محجوزة. لا تزال ملفات ذاكرة التخزين المؤقت المحلية تخزن النص العادي المستعاد: هدف الإخفاء هو إرسال API فقط.

    يمكن إنشاء قاموس بواسطة أداة خارجية -- على سبيل المثال نموذج محلي يستخرج الكيانات الحساسة:

        llm -m <local-model> \
            -s 'Extract sensitive entities as a JSON array of objects
                with "category" and "text" fields.' \
            < report.md > report.anon.json
        greple -Mxlate --xlate-anonymize=report.anon.json ...

    يُتسامح مع BOM بصيغة UTF-8 في الملف. قد تحمل القيم في تنسيق أسطر المادة الأمامية تعليقًا لاحقًا فقط على سطر مستقل، وليس بعد القيمة.

- **--xlate-anonymize-mark**\[=_regex_\]

    اجمع إدخالات إخفاء الهوية من العلامات المضمّنة في المستند نفسه. علّم أول ظهور مثل `{{ person("山田太郎") }}` وسيُخفى كل ظهور للسلسلة في كامل المستند. تبقى العلامة نفسها في المصدر وفي الترجمة، لذلك يمكن أيضًا معالجة المستند بواسطة معالج ماكرو بأسلوب Jinja2 (عرّف الماكرو `person` لطباعة الاسم أو حجبه). يجب أن يحتوي _regex_ مخصص على الالتقاطين المسمّيين `(?<category>...)` و`(?<text>...)`.

    لاحظ أنه مع خيار ذي قيمة اختيارية مثل هذا، سيُؤخذ وسيط الملف التالي كقيمة: اكتب `--xlate-anonymize-mark=` (مع `=` لاحق) عند استخدام الترميز الافتراضي.

    يمكن تكوين ترميزات بديلة، على سبيل المثال `--xlate-anonymize-mark='@@(?<category>[a-z][a-z0-9_]*):(?<text>[^\n]+?)@@'` لعلامات بأسلوب `@@person:NAME@@`، أو صيغة تعليق HTML تبقى غير مرئية في Markdown المعروض. تُجمع قواعد العلامات لكل مستند: السلسلة المعلّمة في ملف إدخال واحد لا تُخفى في ملف آخر من التشغيل نفسه (بخلاف قيم المادة الأمامية، التي تتراكم عبر الملفات).

- **--xlate-template**\[=_regex_\]

    عامِل تعبيرات القوالب (الافتراضي: Jinja2 `{{ ... }}`، `{% ... %}`، `{# ... #}`) كعناصر نائبة معتمة: وجّه النموذج إلى نسخها دون تغيير والتحقق، لكل كتلة، من أن الاستجابة تحتوي بالضبط على التعبيرات نفسها، وبالعدد نفسه من المرات لكل منها. قد يتغير ترتيبها، لأن الترجمة قد تعيد ترتيبها بشكل مشروع لتتبع ترتيب كلمات اللغة الهدف. يؤدي التعبير المعطوب إلى إجهاض التشغيل؛ وتُحفظ ذاكرة التخزين المؤقت كنقطة تحقق وتُجمّد، بحيث لا يضيع أي شيء مدفوع الثمن.

    لاحظ أنه مع خيار ذي قيمة اختيارية مثل هذا، ستُعد وسيطة الملف التالية قيمةً له: اكتب `--xlate-template=` (مع `=` لاحقة) عند استخدام الترميز الافتراضي.

- **--xlate-frontmatter**

    عامِل كتلة بادئة `---` ... `---` كواجهة أمامية YAML: استثنِها من الترجمة ومن شرائح سياق المرحلة 2، وأضف قيم `key: value` المسطّحة الخاصة بها إلى قواعد إخفاء الهوية (الفئة `var`) كشبكة أمان. عند وجود ملفات إدخال متعددة، تتراكم القيم المجمّعة (مع الميل إلى جانب الإخفاء).

    اترك دائمًا سطرًا فارغًا بعد `---` الختامية. مع نمط مطابقة بأسلوب الفقرات، فإن الواجهة الأمامية التي تمتد مباشرة إلى نص المتن تُشكّل كتلة واحدة عابرة للحدود لا يمكن للاستثناء كبتها (تُطبع رسالة تحذير في هذه الحالة)؛ تظل القيم مجهولة الهوية، لكن الواجهة الأمامية نفسها ستُرسل للترجمة.

- **--xlate-glossary**=_glossary_

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

- **--xlate-dryrun**

    لا تستدعِ واجهة برمجة تطبيقات الترجمة؛ بل اعرض، من خلال عرض التقدم، كل حمولة بالضبط كما كانت ستُرسَل (بعد إخفاء الهوية والتقنيع). مفيد للتحقق مما يغادر الجهاز ولتقدير تكلفة التشغيل.

- **--**\[**no-**\]**xlate-progress** (Default: True)

    اعرض نتيجة الترجمة في الوقت الحقيقي في مخرجات STDERR. تُعرض حمولة `From` كما أُرسلت، بعد إخفاء الهوية والتقنيع.

- **--xlate-stripe**

    استخدم وحدة [App::Greple::stripe](https://metacpan.org/pod/App%3A%3AGreple%3A%3Astripe) لإظهار الجزء المطابق بأسلوب التظليل المخطط (zebra striping). يكون هذا مفيدًا عندما تكون الأجزاء المتطابقة متصلة على التوالي.

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

- **--xlate-mask**

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

- **--match-all**

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

- **--lineify-cm**
- **--lineify-colon**

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

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

# CACHE OPTIONS

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

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

- --xlate-cache=_strategy_
    - `auto` (Default)

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

    - `create`

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

    - `always`, `yes`, `1`

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

    - `clear`

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

    - `never`, `no`, `0`

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

    - `accumulate`

        وفقًا للسلوك الافتراضي، تتم إزالة البيانات غير المستخدمة من ملف ذاكرة التخزين المؤقت. إذا كنت لا تريد إزالتها وتريد الاحتفاظ بها في الملف، استخدم `accumulate`.
- **--xlate-update**

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

# COMMAND LINE INTERFACE

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

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

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

تتم إدارة عمليات Docker بواسطة [App::dozo](https://metacpan.org/pod/App%3A%3Adozo)، والذي يمكن استخدامه أيضًا كأمر مستقل. يدعم أمر `dozo` ملف الإعدادات `.dozorc` لإعدادات الحاوية الدائمة.

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

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

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

اقرأ المقال الياباني في قسم ["SEE ALSO"](#see-also) للتفاصيل.

# EMACS

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

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

# ENVIRONMENT

- DEEPL\_AUTH\_KEY

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

- OPENAI\_API\_KEY

    مفتاح مصادقة OpenAI، يُستخدم بواسطة محركات **gpty** القديمة. يقرأ محرك **gpt5** المستند إلى `llm` هذا المتغير أيضًا، لكن المفاتيح المخزنة باستخدام `llm keys set openai` تعمل أيضًا.

- GREPLE\_XLATE\_CACHE

    عيّن استراتيجية التخزين المؤقت الافتراضية (انظر ["CACHE OPTIONS"](#cache-options)).

# INSTALL

## CPANMINUS

    $ cpanm App::Greple::xlate

## TOOLS

ثبّت أداة سطر الأوامر للمحرك الذي تستخدمه: `llm` لمحرك **gpt5**، و`deepl` لـ DeepL، و`gpty` لمحركات GPT القديمة.

[https://llm.datasette.io/](https://llm.datasette.io/)

[https://github.com/DeepLcom/deepl-python](https://github.com/DeepLcom/deepl-python)

[https://github.com/tecolicom/App-gpty](https://github.com/tecolicom/App-gpty)

# SEE ALSO

## MODULES

[App::Greple::xlate::llm](https://metacpan.org/pod/App%3A%3AGreple%3A%3Axlate%3A%3Allm), [App::Greple::xlate::deepl](https://metacpan.org/pod/App%3A%3AGreple%3A%3Axlate%3A%3Adeepl)

[App::dozo](https://metacpan.org/pod/App%3A%3Adozo) - مشغّل Docker عام يُستخدم بواسطة xlate لعمليات الحاويات

## RELATED MODULES

- [App::Greple](https://metacpan.org/pod/App%3A%3AGreple)

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

- [App::Greple::update](https://metacpan.org/pod/App%3A%3AGreple%3A%3Aupdate)

    يمكنك استخدام وحدة `-Mupdate` لتعديل الملفات بنتيجة أمر **greple**.

- [App::sdif](https://metacpan.org/pod/App%3A%3Asdif)

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

- [App::Greple::stripe](https://metacpan.org/pod/App%3A%3AGreple%3A%3Astripe)

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

## RESOURCES

- [https://hub.docker.com/r/tecolicom/xlate](https://hub.docker.com/r/tecolicom/xlate)

    صورة حاوية Docker.

- [https://github.com/tecolicom/getoptlong](https://github.com/tecolicom/getoptlong)

    مكتبة `getoptlong.sh` المستخدمة لتحليل الخيارات في البرنامج النصي `xlate` و[App::dozo](https://metacpan.org/pod/App%3A%3Adozo).

- [https://llm.datasette.io/](https://llm.datasette.io/)

    الأمر `llm` الذي يستخدمه المحرك **gpt5** للوصول إلى نماذج LLM.

- [https://github.com/DeepLcom/deepl-python](https://github.com/DeepLcom/deepl-python)

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

- [https://github.com/openai/openai-python](https://github.com/openai/openai-python)

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

- [https://github.com/tecolicom/App-gpty](https://github.com/tecolicom/App-gpty)

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

## ARTICLES

- [https://qiita.com/kaz-utashiro/items/1c1a51a4591922e18250](https://qiita.com/kaz-utashiro/items/1c1a51a4591922e18250)

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

- [https://qiita.com/kaz-utashiro/items/a5e19736416ca183ecf6](https://qiita.com/kaz-utashiro/items/a5e19736416ca183ecf6)

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

- [https://qiita.com/kaz-utashiro/items/1b9e155d6ae0620ab4dd](https://qiita.com/kaz-utashiro/items/1b9e155d6ae0620ab4dd)

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

# AUTHOR

Kazumasa Utashiro

# LICENSE

Copyright © 2023-2026 Kazumasa Utashiro.

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