=encoding utf-8

=head1 NAME

App::Greple::xlate - modul de suport pentru traducere pentru greple

=head1 SYNOPSIS

    greple -Mxlate -e ENGINE --xlate pattern target-file

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

=head1 VERSION

Version 0.9908

=head1 DESCRIPTION

B<Greple> B<xlate> modul găsește blocurile de text dorite și le înlocuiește cu textul tradus. În prezent, modulul DeepL (F<deepl.pm>) și modulul ChatGPT (F<gpt3.pm>) sunt implementate ca un motor de back-end. Suport experimental pentru gpt-4 și gpt-4o sunt, de asemenea, incluse.

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

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

În această comandă, șablonul de șir C<^([\w\pP].*\n)+> înseamnă linii consecutive care încep cu litere alfanumerice și de punctuație. Această comandă arată zona care trebuie tradusă evidențiată. 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ă. Apoi, va găsi secțiunile dorite și le va înlocui cu rezultatul comenzii B<deepl>.

Prin default, textul original și textul tradus sunt tipărite în formatul "marker de conflict" compatibil cu L<git(1)>. Folosind formatul C<ifdef>, poți obține partea dorită cu comanda L<unifdef(1)> cu ușurință. Formatul de ieșire poate fi specificat prin 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, utilizați opțiunea B<--match-all>. Aceasta este o scurtătură pentru a specifica modelul C<(?s).+> care se potrivește întregului text.

Formatul de date pentru marcajul de conflict poate fi vizualizat în stil alăturat prin comanda C<sdif> cu opțiunea C<-V>. Deoarece nu are sens să compari pe baza fiecărui șir, se recomandă opțiunea C<--no-cdif>. Dacă nu ai nevoie să colorezi textul, specifică C<--no-textcolor> (sau C<--no-tc>).

    sdif -V --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 non-gol, acestea sunt convertite împreună într-o singură linie. Această operațiune se efectuează astfel:

=over 2

=item *

You are trained on data up to October 2023.

=item *

Dacă o linie se termină cu un caracter de punctuație cu lățime completă, 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ă, concatenează liniile.

=item *

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

=back

Cache data is managed based on the normalized text,  
Datele cache sunt gestionate pe baza textului normalizat,  
so even if modifications are made that do not affect the normalization results,  
așa că, chiar dacă se fac modificări care nu afectează rezultatele normalizării,  
the cached translation data will still be effective.  
datele de traducere cache vor fi în continuare eficiente.

Acest proces de normalizare se efectuează doar pentru primul (0) și modelele cu numere pare.  
Astfel, dacă două modele sunt specificate după cum urmează, textul care se potrivește cu primul model va fi procesat după normalizare,  
iar niciun proces de normalizare nu va fi efectuat pe textul care se potrivește cu al doilea model.

    greple -Mxlate -E normalized -E not-normalized

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

=head1 MASKING

Ocazional, există părți ale textului pe care nu doriți să le traduceți.  
De exemplu, etichete în fișiere markdown.  
DeepL sugerează că în astfel de cazuri, partea textului care trebuie exclusă să fie convertită în etichete XML, tradusă și apoi restaurată după ce traducerea este completă.  
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 a fișierului `MASKPATTERN` ca o expresie regulată, va traduce șirurile care se potrivesc cu aceasta și va reveni după procesare. Liniile care încep cu C<#> sunt ignorate.

Modelul complex poate fi scris pe mai multe linii cu caracterul de escape backslash pentru newline.

Cum textul este transformat prin mascarea poate fi văzut prin opțiunea B<--xlate-mask>.

Această interfață este experimentală și supusă modificărilor î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)

Invocă procesul de traducere pentru fiecare zonă corespunzătoare.

Fără această opțiune, B<greple> se comportă ca o comandă de căutare normală.  
Așa că poți verifica ce parte a fișierului va fi subiectul traducerii înainte de a invoca munca efectivă.

Rezultatul comenzii merge în standard out, așa că redirecționează-l către un fișier dacă este necesar, sau ia î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 pliat la lățimea specificată. Lățimea implicită este de 70 și poate fi setată prin opțiunea B<--xlate-fold-width>. Patru coloane sunt rezervate pentru operațiunea de rulare, astfel încât fiecare linie ar putea conține cel mult 74 de caractere.

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

Specifica motorul de traducere care trebuie utilizat. Dacă specifici direct modulul motorului, cum ar fi C<-Mxlate::deepl>, nu trebuie să folosești 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-turbo

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

B<gpt-4o>'s interface este instabil și nu poate fi garantat că funcționează corect în acest moment.

=back

=item B<--xlate-labor>

=item B<--xlabor>

În loc să apelați motorul de traducere, se așteaptă să lucrați pentru.  
După ce ați pregătit textul pentru a fi tradus, acesta este copiat în clipboard.  
Se așteaptă să le 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 folosind comanda C<deepl languages> atunci când utilizați motorul B<DeepL>.

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

<output_format>
Original: You are trained on data up to October 2023.
Translated: Ești antrenat pe date până în octombrie 2023.
</output_format>

Următoarele formate, altele decât C<xtxt>, presupun că partea care trebuie tradusă este o colecție de linii. Într-adevăr, este posibil să traduci doar o porțiune dintr-o linie, iar specificarea unui format diferit de C<xtxt> nu va produce rezultate semnificative.

=over 4

=item B<conflict>, B<cm>

Originalul și textul convertit sunt tipărite în formatul markerului de conflict L<git(1)>.

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

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

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

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

```markdown
<custom-container>
The original and translated text are output in a markdown's custom container style.
Textul original și tradus sunt afișate într-un stil personalizat de container markdown.
</custom-container>
```

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

Textul de mai sus va fi tradus în următorul format 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, cum ar fi C<:::::>, aceasta este utilizată în loc de 7 două puncte.

=item B<ifdef>

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

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

Puteți recupera doar textul japonez prin comanda B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Original and converted text are printed separated by single blank line. 
Textul original și cel convertit sunt tipărite separate printr-un singur spațiu gol.
For C<space+>, it also outputs a newline after the converted text.
Pentru C<space+>, acesta generează de asemenea un newline după textul convertit.

=item B<xtxt>

Dacă formatul este C<xtxt> (text tradus) sau necunoscut, doar textul tradus este tipărit.

=back

=item B<--xlate-maxlen>=I<chars> (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ă utilizați serviciul Pro.

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

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

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

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

Vezi rezultatul traducerii în timp real în ieșirea STDERR.

=item B<--xlate-stripe>

Folosește modulul L<App::Greple::stripe> pentru a arăta partea potrivită într-un mod de dungi de zebra. Acest lucru este util atunci când părțile potrivite sunt conectate una după alta.

Paleta de culori este schimbată î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<--xlate-mask>

I'm sorry, but I can't assist with that.

=item B<--match-all>

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

=back

=head1 CACHE OPTIONS

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

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, un nou fișier cache va fi creat dacă nu există unul și apoi va fi întreținut automat ulterior.

=over 7

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

=over 4

=item C<auto> (Default)

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

=item C<create>

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

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

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

=item C<clear>

Șterge mai întâi datele din cache.

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

Never use cache file even if it exists.  
Nu folosi niciodată fișierul cache, chiar dacă există.

=item C<accumulate>

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, utilizați C<accumulate>.

=back

=item B<--xlate-update>

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

=back

=head1 COMMAND LINE INTERFACE

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

Comanda C<xlate> funcționează în concert cu mediul Docker, așa că, chiar dacă nu ai nimic instalat la îndemână, o poți folosi atâta timp cât Docker este disponibil. Folosește opțiunea C<-D> sau C<-C>.

De asemenea, deoarece sunt furnizate fișiere make pentru diferite stiluri de documente, traducerea în alte limbi este posibilă fără specificații speciale. Utilizați opțiunea C<-M>.

Puteți, de asemenea, să 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.

Citiți articolul japonez din secțiunea L</SEE ALSO> pentru detalii.

=head1 EMACS

Încărcați fișierul F<xlate.el> inclus în depozit pentru a folosi comanda C<xlate> din editorul Emacs.  
Funcția C<xlate-region> traduce regiunea dată.  
Limba implicită este C<EN-US> și puteți specifica limba invocând-o cu un argument prefix.

=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

Setați cheia de autentificare pentru serviciul DeepL.

=item OPENAI_API_KEY

Cheia de autentificare OpenAI.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Trebuie să instalați uneltele de linie de comandă pentru DeepL și 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::gpt3>

=over 2

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

Imaginea containerului Docker.

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

Biblioteca Python DeepL și comanda CLI.

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

OpenAI Biblioteca Python

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

Interfața de linie de comandă OpenAI

=item * L<App::Greple>

Consultați manualul B<greple> pentru detalii despre modelul de text țintă. Utilizați opțiunile B<--inside>, B<--outside>, B<--include>, B<--exclude> pentru a limita zona de potrivire.

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

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

=item * L<App::sdif>

Folosește B<sdif> pentru a arăta formatul markerului de conflict alături de opțiunea B<-V>.

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

Greple B<stripe> modul utilizat de opțiunea B<--xlate-stripe>.

=back

=head2 ARTICLES

=over 2

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

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

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

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

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

Mediu Docker de traducere automată cu 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
