=encoding utf-8

=head1 NAME

App::Greple::xlate - modul de suport pentru traducere pentru 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> modulul găsește blocurile de text dorite și le înlocuiește cu textul tradus. În prezent, modulele DeepL (F<deepl.pm>), ChatGPT 4.1 (F<gpt4.pm>) și GPT-5 (F<gpt5.pm>) sunt implementate ca motoare back-end.

Dacă doriți să traduceți blocuri normale de text într-un document scris în stilul pod al Perl, folosiți comanda B<greple> cu C<xlate::deepl> și modulul C<perl> astfel:

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

În această comandă, șirul de pattern C<^([\w\pP].*\n)+> înseamnă linii consecutive care încep cu litere alfanumerice sau semne de punctuație. Această comandă evidențiază zona care urmează să fie tradusă. Opțiunea B<--all> este folosită pentru a produce întregul text.

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

Apoi adăugați opțiunea C<--xlate> pentru a traduce zona selectată. Astfel, va găsi secțiunile dorite și le va înlocui cu rezultatul comenzii B<deepl>.

În mod implicit, textul original și cel tradus sunt tipărite în formatul „conflict marker” compatibil cu L<git(1)>. Folosind formatul C<ifdef>, puteți obține partea dorită cu comanda L<unifdef(1)> cu ușurință. Formatul de ieșire poate fi specificat cu opțiunea 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>

Dacă doriți să traduceți întregul text, folosiți opțiunea B<--match-all>. Aceasta este o scurtătură pentru a specifica pattern-ul C<(?s).+> care se potrivește cu întregul text.

Datele în format de marcator de conflict pot fi vizualizate în stil side-by-side prin comanda L<sdif|App::sdif> cu opțiunea C<-V>. Deoarece nu are sens să comparați pe bază de șir, se recomandă opțiunea C<--no-cdif>. Dacă nu aveți nevoie să colorați textul, specificați C<--no-textcolor> (sau 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

Procesarea se face în unități specificate, dar în cazul unei secvențe de mai multe linii de text ne-goale, acestea sunt convertite împreună într-o singură linie. Această operațiune se realizează astfel:

=over 2

=item *

Se elimină spațiile albe de la începutul și sfârșitul fiecărei linii.

=item *

Dacă o linie se termină cu un caracter de punctuație de lățime completă, se concatenează cu linia următoare.

=item *

Dacă o linie se termină cu un caracter de lățime completă și linia următoare începe cu un caracter de lățime completă, liniile se concatenează.

=item *

Dacă fie sfârșitul, fie începutul unei linii nu este un caracter de lățime completă, se concatenează prin inserarea unui spațiu.

=back

Datele din cache sunt gestionate pe baza textului normalizat, astfel încât chiar dacă se fac modificări care nu afectează rezultatele normalizării, datele de traducere din cache vor rămâne valabile.

Acest proces de normalizare se efectuează doar pentru primul (al 0-lea) și pentru pattern-urile cu număr par. Astfel, dacă sunt specificate două pattern-uri ca mai jos, textul care se potrivește cu primul pattern va fi procesat după normalizare, iar pe textul care se potrivește cu al doilea pattern nu se va efectua nicio normalizare.

    greple -Mxlate -E normalized -E not-normalized

Prin urmare, folosiți primul pattern pentru textul care trebuie procesat prin combinarea mai multor linii într-una singură și folosiți al doilea pattern pentru textul pre-formatat. Dacă nu există text care să se potrivească cu primul pattern, folosiți un pattern care nu se potrivește cu nimic, cum ar fi C<(?!)>.

=head1 MASKING

Ocazional, există părți din text pe care nu doriți să le traduceți. De exemplu, etichetele din fișierele markdown. DeepL sugerează ca, în astfel de cazuri, partea de text care trebuie exclusă să fie convertită în etichete XML, tradusă, apoi restaurată după finalizarea traducerii. Pentru a susține acest lucru, este posibil să specificați părțile care trebuie mascate de la traducere.

    --xlate-setopt maskfile=MASKPATTERN

Acest lucru va interpreta fiecare linie din fișierul `MASKPATTERN` ca o expresie regulată, va traduce șirurile care se potrivesc și va reveni după procesare. Liniile care încep cu C<#> sunt ignorate.

Un model complex poate fi scris pe mai multe linii cu newline scăpat cu backslash.

Modul în care textul este transformat prin mascarea poate fi văzut cu opțiunea B<--xlate-mask>.

Această interfață este experimentală și poate suferi modificări în viitor.

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

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

Invocați procesul de traducere pentru fiecare zonă potrivită.

Fără această opțiune, B<greple> se comportă ca o comandă de căutare normală. Astfel, puteți verifica ce parte a fișierului va fi supusă traducerii înainte de a lansa efectiv procesul.

Rezultatul comenzii este trimis la ieșirea standard, deci redirecționați către un fișier dacă este necesar sau luați în considerare utilizarea modulului L<App::Greple::update>.

Opțiunea B<--xlate> apelează opțiunea B<--xlate-color> cu opțiunea B<--color=never>.

Cu opțiunea B<--xlate-fold>, textul convertit este împărțit pe lățimea specificată. Lățimea implicită este 70 și poate fi setată cu opțiunea B<--xlate-fold-width>. Patru coloane sunt rezervate pentru operațiunea run-in, astfel încât fiecare linie poate conține cel mult 74 de caractere.

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

Specifică motorul de traducere care va fi folosit. Dacă specificați direct modulul motorului, cum ar fi C<-Mxlate::deepl>, nu este necesar să folosiți această opțiune.

În acest moment, următoarele motoare sunt disponibile

=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

Interfața B<gpt-4o> este instabilă și nu se poate garanta că funcționează corect în acest moment.

=item * B<gpt5>: gpt-5

=back

=item B<--xlate-labor>

=item B<--xlabor>

În loc să apelați motorul de traducere, se așteaptă să lucrați manual. După pregătirea textului de tradus, acesta este copiat în clipboard. Se așteaptă să îl lipiți în formular, să copiați rezultatul în clipboard și să apăsați return.

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

Specificați limba țintă. Puteți obține limbile disponibile cu comanda C<deepl languages> atunci când folosiți motorul B<DeepL>.

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

Specificați formatul de ieșire pentru textul original și cel tradus.

Următoarele formate, altele decât C<xtxt>, presupun că partea de tradus este o colecție de linii. De fapt, este posibil să traduceți doar o porțiune dintr-o linie, dar specificarea unui format diferit de C<xtxt> nu va produce rezultate semnificative.

=over 4

=item B<conflict>, B<cm>

Textul original și cel convertit sunt tipărite în formatul marker de conflict L<git(1)>.

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

Puteți recupera fișierul original cu următoarea comandă L<sed(1)>.

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

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

Textul original și cel tradus sunt afișate în stilul container personalizat al markdown-ului.

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

Textul de mai sus va fi tradus astfel în HTML.

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

Numărul de două puncte este 7 în mod implicit. Dacă specificați o secvență de două puncte ca C<:::::>, aceasta va fi folosită în loc de 7 două puncte.

=item B<ifdef>

Textul original și cel convertit sunt tipărite în formatul L<cpp(1)> C<#ifdef>.

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

Puteți prelua doar textul japonez cu comanda B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Textul original și cel convertit sunt tipărite separate printr-un singur rând gol.

=item B<xtxt>

Pentru C<space+>, de asemenea, se afișează un rând nou după textul convertit.

=back

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

Dacă formatul este C<xtxt> (text tradus) sau necunoscut, se afișează doar textul tradus.

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

Specificați lungimea maximă a textului care poate fi trimis la API odată. Valoarea implicită este setată ca pentru serviciul gratuit DeepL: 128K pentru API (B<--xlate>) și 5000 pentru interfața clipboard (B<--xlate-labor>). Este posibil să puteți schimba aceste valori dacă folosiți serviciul Pro.

Specificați numărul maxim de linii de text care pot fi trimise la API odată.

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

Specificați un prompt personalizat care va fi trimis motorului de traducere. Această opțiune este disponibilă doar atunci când utilizați motoarele ChatGPT (gpt3, gpt4, gpt4o). Puteți personaliza comportamentul traducerii oferind instrucțiuni specifice modelului AI. Dacă promptul conține C<%s>, acesta va fi înlocuit cu numele limbii țintă.

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

Specificați informații suplimentare de context care vor fi trimise motorului de traducere. Această opțiune poate fi folosită de mai multe ori pentru a furniza mai multe șiruri de context. Informațiile de context ajută motorul de traducere să înțeleagă fundalul și să producă traduceri mai precise.

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

Specificați un ID de glosar care va fi folosit pentru traducere. Această opțiune este disponibilă doar atunci când utilizați motorul DeepL. ID-ul de glosar trebuie obținut din contul dumneavoastră DeepL și asigură traducerea consecventă a anumitor termeni.

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

Setați această valoare la 1 dacă doriți să traduceți o linie odată. Această opțiune are prioritate față de opțiunea C<--xlate-maxlen>.

=item B<--xlate-stripe>

Vedeți rezultatul traducerii în timp real în ieșirea STDERR.

Folosiți modulul L<App::Greple::stripe> pentru a evidenția partea potrivită în stil zebra striping. Acest lucru este util când părțile potrivite sunt conectate una după alta.

=item B<--xlate-mask>

Paleta de culori este comutată în funcție de culoarea de fundal a terminalului. Dacă doriți să specificați explicit, puteți folosi B<--xlate-stripe-light> sau B<--xlate-stripe-dark>.

=item B<--match-all>

Efectuați funcția de mascarea și afișați textul convertit așa cum este, fără restaurare.

=item B<--lineify-cm>

=item B<--lineify-colon>

În cazul formatelor C<cm> și C<colon>, ieșirea este împărțită și formatată linie cu linie. Prin urmare, dacă doar o parte a unei linii trebuie tradusă, rezultatul așteptat nu poate fi obținut. Aceste filtre corectează ieșirea care este coruptă prin traducerea unei părți dintr-o linie într-o ieșire normală, linie cu linie.

În implementarea actuală, dacă mai multe părți ale unei linii sunt traduse, acestea sunt afișate ca linii independente.

=back

=head1 CACHE OPTIONS

Setați întregul text al fișierului ca zonă țintă.

Modulul B<xlate> poate stoca textul tradus în cache pentru fiecare fișier și îl poate citi înainte de execuție pentru a elimina timpul de așteptare la server. Cu strategia implicită de cache C<auto>, menține datele în cache doar când există un fișier cache pentru fișierul țintă.

=over 7

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

=over 4

=item C<auto> (Default)

Folosiți B<--xlate-cache=clear> pentru a iniția gestionarea cache-ului sau pentru a curăța toate datele cache existente. Odată executat cu această opțiune, va fi creat un fișier cache nou dacă nu există deja și apoi va fi menținut automat ulterior.

=item C<create>

Menține fișierul cache dacă există.

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

Creează un fișier cache gol și iese.

=item C<clear>

Menține cache-ul oricum, atâta timp cât ținta este un fișier normal.

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

Șterge mai întâi datele din cache.

=item C<accumulate>

Nu folosi niciodată fișierul cache, chiar dacă există.

=back

=item B<--xlate-update>

Prin comportamentul implicit, datele neutilizate sunt eliminate din fișierul cache. Dacă nu doriți să le eliminați și să le păstrați în fișier, folosiți C<accumulate>.

=back

=head1 COMMAND LINE INTERFACE

Această opțiune forțează actualizarea fișierului cache chiar dacă nu este necesar.

Comanda C<xlate> suportă opțiuni lungi în stil GNU, cum ar fi C<--to-lang>, C<--from-lang>, C<--engine> și C<--file>. Folosiți C<xlate -h> pentru a vedea toate opțiunile disponibile.

Puteți folosi cu ușurință acest modul din linia de comandă folosind comanda C<xlate> inclusă în distribuție. Consultați pagina de manual C<xlate> pentru utilizare.

Operațiunile Docker sunt gestionate de scriptul C<xrun>, care poate fi folosit și ca o comandă de sine stătătoare. Scriptul C<xrun> suportă fișierul de configurare C<.xrunrc> pentru setări persistente ale containerului.

Comanda C<xlate> funcționează în colaborare cu mediul Docker, astfel încât chiar dacă nu aveți nimic instalat local, o puteți folosi atâta timp cât Docker este disponibil. Folosiți opțiunea C<-D> sau C<-C>.

De asemenea, deoarece sunt furnizate makefile-uri pentru diverse stiluri de documente, traducerea în alte limbi este posibilă fără specificații speciale. Folosiți opțiunea C<-M>.

Puteți combina și opțiunile Docker și C<make> astfel încât să puteți rula C<make> într-un mediu Docker.

Rularea ca C<xlate -C> va lansa un shell cu depozitul git curent montat.

=head1 EMACS

Încarcă fișierul F<xlate.el> inclus în depozit pentru a folosi comanda C<xlate> din editorul Emacs. 

=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

Funcția C<xlate-region> traduce regiunea dată. Limba implicită este C<EN-US> și poți specifica limba invocând-o cu argument prefix.

=item OPENAI_API_KEY

Setează cheia ta de autentificare pentru serviciul DeepL.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Cheie de autentificare OpenAI.

Trebuie să instalezi unelte de linie de comandă pentru DeepL și ChatGPT.

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

=head1 SEE ALSO

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

L<App::Greple::xlate>

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

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

=over 2

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

L<App::Greple::xlate::gpt3>

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

Biblioteca C<getoptlong.sh> este folosită pentru analiza opțiunilor în scripturile C<xlate> și C<xrun>.

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

Imagine container Docker.

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

Bibliotecă Python DeepL și comandă CLI.

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

Bibliotecă Python OpenAI

=item * L<App::Greple>

Interfață de linie de comandă OpenAI

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

Vezi manualul B<greple> pentru detalii despre modelul textului țintă. Folosește opțiunile B<--inside>, B<--outside>, B<--include>, B<--exclude> pentru a limita zona de potrivire.

=item * L<App::sdif>

Poți folosi modulul C<-Mupdate> pentru a modifica fișierele în funcție de rezultatul comenzii B<greple>.

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

Folosește B<sdif> pentru a afișa formatul markerului de conflict alăturat cu opțiunea B<-V>.

=back

=head2 ARTICLES

=over 2

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

Modulul Greple B<stripe> se folosește cu opțiunea B<--xlate-stripe>.

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

Modul Greple pentru a traduce și înlocui doar părțile necesare cu API-ul DeepL (în japoneză)

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

Generarea documentelor în 15 limbi cu modulul API DeepL (în japoneză)

=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
