=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

Modulul B<Greple> B<xlate> găsește blocurile de text dorite și le înlocuiește cu textul tradus. În prezent, modulul DeepL (F<deepl.pm>) și ChatGPT (F<gpt3.pm>) sunt implementate ca motoare de bază. Suportul experimental pentru gpt-4 și gpt-4o este, de asemenea, inclus.

Dacă doriți să traduceți blocurile de text normale dintr-un document scris în stilul pod al Perl, utilizați comanda B<greple> cu modulul C<xlate::deepl> și C<perl> în felul următor:

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

În această comandă, șirul de tipar 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>.

În mod implicit, textul original și textul tradus sunt afișate în formatul "conflict marker", compatibil cu L<git(1)>. Utilizând formatul C<ifdef>, puteți obține partea dorită cu ușurință folosind comanda L<unifdef(1)>. 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 cu întregul text.

Formatul datelor pentru markerul de conflict poate fi vizualizat în stil side-by-side folosind comanda C<sdif> cu opțiunea C<-V>. Deoarece nu are sens să comparăm pe baza fiecărui șir de caractere, 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-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-gol, acestea sunt convertite împreună într-o singură linie. Această operație se efectuează astfel:

=over 2

=item *

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

=item *

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

=item *

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

=back

Datele 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 cache vor fi în continuare eficiente.

Acest proces de normalizare este efectuat doar pentru primul (0-lea) și pentru modelul cu număr par. Prin urmare, dacă sunt specificate două modele 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 urmează să fie procesat prin combinarea mai multor linii într-o singură linie, și folosiți al doilea model pentru textul preformatat. 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

Uneori, există părți ale textului pe care nu dorești să le traduci. De exemplu, tag-urile din fișierele markdown. DeepL sugerează că în astfel de cazuri, partea de text de exclus să fie convertită în tag-uri XML, tradusă, și apoi restaurată după ce traducerea este completă. Pentru a susține acest lucru, este posibil să specifici părțile care trebuie mascate de la traducere.

    --xlate-setopt maskfile=MASKPATTERN

Acesta va interpreta fiecare linie a fișierului `MASKPATTERN` ca o expresie regulată, va traduce șirurile care se potrivesc cu ea, și va reveni la forma inițială după procesare. Liniile care încep cu C<#> sunt ignorate.

Un model complex poate fi scris pe mai multe linii cu o linie nouă scrisă cu backslash.

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

Această interfață este experimentală și este supusă unor posibile schimbă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ă. Deci puteți verifica care parte a fișierului va fi supusă traducerii înainte de a invoca lucrul efectiv.

Rezultatul comenzii este trimis la ieșirea standard, deci redirecționați-l într-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 pliat în funcție de 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ția 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 trebuie utilizat. Dacă specifici direct modulul motorului, cum ar fi C<-Mxlate::deepl>, nu este nevoie 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

Interfața lui B<gpt-4o> 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 el. După ce ați pregătit textul pentru a fi 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 Enter.

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

Specificați limba țintă. Puteți obține limbile disponibile prin comanda C<deepl languages> atunci când utilizaț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.

Formatele următoare, în afara C<xtxt>, presupun că partea de tradus este o colecție de linii. De fapt, 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>

Textul original și cel convertit sunt tipărite în formatul de marcare a conflictelor 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<:::::::>

```html

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

<div class="original">

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

Numărul de două puncte este 7 în mod implicit. Dacă specifici o secvență de două puncte ca C<:::::>, aceasta este 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 recupera doar textul japonez cu comanda B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Original text:

=item B<xtxt>

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

=back

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

Traduceți următorul text în limba română, linie cu linie.

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

Specifică numărul maxim de linii de text care vor fi trimise la API odată.

Setează această valoare la 1 dacă vrei să traduci câte o linie pe rând. Această opțiune primește prioritate față de opțiunea C<--xlate-maxlen>.

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

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

=item B<--xlate-stripe>

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

Paleta de culori se schimbă î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>

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

=item B<--match-all>

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

=back

=head1 CACHE OPTIONS

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

Folosește B<--xlate-cache=clear> pentru a iniția gestionarea cache-ului sau pentru a curăța toate datele de cache existente. Odată ce este executat cu această opțiune, un nou fișier de cache va fi creat dacă nu există deja ș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>

Creați un fișier cache gol și ieșiți.

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

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

=item C<clear>

Ștergeți mai întâi datele cache.

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

Nu utilizați niciodată fișierul cache chiar dacă există.

=item C<accumulate>

În mod 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 de cache chiar dacă nu este necesar.

=back

=head1 COMMAND LINE INTERFACE

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.

Comanda C<xlate> funcționează în concordanță cu mediul Docker, deci chiar dacă nu aveți nimic instalat la îndemână, puteți să-l utilizați atâta timp cât Docker este disponibil. Utilizați 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>.

De asemenea, puteți combina 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 de lucru curent montat.

Citiți articolul în limba japoneză din secțiunea "VEZI ȘI" pentru detalii.

=head1 EMACS

Încărcați fișierul F<xlate.el> inclus în depozit pentru a utiliza 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 prin invocarea acesteia cu un argument de 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ă instalezi instrumentele 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>

Bibliotecă Python DeepL și comandă CLI.

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

Biblioteca Python OpenAI

=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 utiliza modulul C<-Mupdate> pentru a modifica fișierele în funcție de rezultatul comenzii B<greple>.

=item * L<App::sdif>

Utilizați B<sdif> pentru a afișa formatul markerului de conflict alături de opțiunea B<-V>.

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

Modulul Greple B<stripe> folosit de opțiunea B<--xlate-stripe>.

=back

=head2 ARTICLES

=over 2

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

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

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

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

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

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