=encoding utf-8

=head1 NAME

App::Greple::xlate - Greple tõlkimise tugimoodul

=head1 SYNOPSIS

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

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

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

=head1 VERSION

Version 1.0202

=head1 DESCRIPTION

B<Greple> B<xlate> moodul leiab soovitud tekstilõigud ja asendab need tõlgitud tekstiga. Praegu on tagapõhimoodulitena rakendatud DeepL (F<deepl.pm>) ja GPT-5.5 (F<gpt5.pm>) moodulid.

Kui soovite tõlkida tavalisi tekstiplokke Perli pod-stiilis kirjutatud dokumendis, kasutage käsku B<greple> koos C<xlate::deepl> ja C<perl> mooduliga niimoodi:

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

Selles käsus tähendab musterjada C<^([\w\pP].*\n)+> järjestikuseid ridu, mis algavad tähtnumbrilise ja kirjavahemärgiga. See käsk näitab tõlgitavat ala esile tõstetud kujul. Valikut B<--all> kasutatakse kogu teksti koostamiseks.

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

Seejärel lisatakse valik C<--xlate>, et tõlkida valitud ala. Seejärel leitakse soovitud lõigud ja asendatakse need käsu B<deepl> väljundiga.

Vaikimisi trükitakse algne ja tõlgitud tekst L<git(1)>-ga ühilduvas "konfliktimärkide" formaadis. Kasutades C<ifdef> formaati, saab soovitud osa hõlpsasti kätte käsuga L<unifdef(1)>. Väljundi formaati saab määrata valikuga 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>

Kui soovite tõlkida kogu teksti, kasutage valikut B<--match-all>. See on otsetee, et määrata muster C<(?s).+>, mis vastab kogu tekstile.

Konfliktimärkide formaadis andmeid saab vaadata kõrvuti, kasutades käsku L<sdif|App::sdif> koos valikuga C<-V>. Kuna stringide kaupa pole mõtet võrrelda, on soovitatav kasutada C<--no-cdif> valikut. Kui teil ei ole vaja teksti värvida, määrake C<--no-textcolor> (või 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

Töötlemine toimub kindlaksmääratud ühikutes, kuid mitme mittetäieliku tekstirea järjestuse korral teisendatakse need kokku üheks reaks. See operatsioon toimub järgmiselt:

=over 2

=item *

Eemaldatakse valge tühik iga rea alguses ja lõpus.

=item *

Kui rida lõpeb täies laiuses kirjavahemärgiga, ühendage see järgmise reaga.

=item *

Kui rida lõpeb täies laiuses märgiga ja järgmine rida algab täies laiuses märgiga, ühendatakse read.

=item *

Kui rea lõpp või algus ei ole täies laiuses märk, ühendage need, lisades tühiku.

=back

Vahemälu andmeid hallatakse normaliseeritud teksti alusel, nii et isegi kui tehakse muudatusi, mis ei mõjuta normaliseerimise tulemusi, on vahemälus olevad tõlkeandmed ikkagi tõhusad.

See normaliseerimisprotsess viiakse läbi ainult esimese (0.) ja paarisnumbrilise mustri puhul. Seega, kui kaks mustrit on määratud järgmiselt, töödeldakse pärast normaliseerimist esimesele mustrile vastavat teksti ja teisele mustrile vastavat teksti ei normaliseerita.

    greple -Mxlate -E normalized -E not-normalized

Seetõttu kasutage esimest mustrit teksti puhul, mida tuleb töödelda mitme rea ühendamise teel üheks reaks, ja teist mustrit eelnevalt vormindatud teksti puhul. Kui esimeses mustris ei ole sobivat teksti, kasutage mustrit, mis ei vasta millelegi, näiteks C<(?!)>.

=head1 MASKING

Mõnikord on tekstiosasid, mida te ei soovi tõlkida. Näiteks markdown-failide sildid. DeepL soovitab sellistel juhtudel konverteerida välja jäetav tekstiosa XML-tähtedeks, tõlkida ja pärast tõlkimise lõpetamist taastada. Selle toetamiseks on võimalik määrata osad, mis tuleb tõlkimisest välja jätta.

    --xlate-setopt maskfile=MASKPATTERN

See tõlgendab faili C<MASKPATTERN> iga rida regulaarse väljendina, tõlgib sellega sobivad stringid ja taastab pärast töötlemist. Ridadega, mis algavad C<#>, ei arvestata.

Keerulise mustri võib kirjutada mitmele reale koos kaldkriipsu eskaga newline.

Seda, kuidas tekst on maskeerimise abil muudetud, saab näha valiku B<--xlate-mask> abil.

See liides on eksperimentaalne ja võib tulevikus muutuda.

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

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

Käivitage tõlkimisprotsess iga sobitatud ala jaoks.

Ilma selle valikuta käitub B<greple> nagu tavaline otsingukäsklus. Seega saate enne tegeliku töö käivitamist kontrollida, millise faili osa kohta tehakse tõlge.

Käsu tulemus läheb standardväljundisse, nii et vajadusel suunake see faili ümber või kaaluge mooduli L<App::Greple::update> kasutamist.

Valik B<--xlate> kutsub B<--xlate-color> valiku B<--color=never> valikul.

Valikuga B<--xlate-fold> volditakse konverteeritud tekst määratud laiusega. Vaikimisi laius on 70 ja seda saab määrata valikuga B<--xlate-fold-width>. Neli veergu on reserveeritud sisselülitamiseks, nii et iga rida võib sisaldada maksimaalselt 74 märki.

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

Määratleb kasutatava tõlkemootori. Kui määrate mootori mooduli otse, näiteks C<-Mxlate::deepl>, ei pea seda valikut kasutama.

Praegu on saadaval järgmised mootorid

=over 2

=item * B<deepl>: DeepL API

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

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

B<gpt-4o> liides on ebastabiilne ja hetkel ei saa garanteerida selle korrektset toimimist.

=item * B<gpt5>: gpt-5.5

=back

=item B<--xlate-labor>

=item B<--xlabor>

Selle asemel, et kutsuda tõlkemootorit, oodatakse tööd. Pärast tõlgitava teksti ettevalmistamist kopeeritakse need lõikelauale. Eeldatakse, et te kleebite need vormi, kopeerite tulemuse lõikelauale ja vajutate return.

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

Määrake sihtkeel. B<DeepL> mootori kasutamisel saate saadaval olevad keeled kätte käsuga C<deepl languages>.

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

Määrake originaal- ja tõlgitud teksti väljundformaat.

Järgmised vormingud, välja arvatud C<xtxt>, eeldavad, et tõlgitav osa on ridade kogum. Tegelikult on võimalik tõlkida ainult osa reast, kuid muu formaadi kui C<xtxt> määramine ei anna mõttekaid tulemusi.

=over 4

=item B<conflict>, B<cm>

Algne ja teisendatud tekst trükitakse L<git(1)> konfliktimärgistuse formaadis.

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

Originaalfaili saate taastada järgmise käsuga L<sed(1)>.

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

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

Algne ja tõlgitud tekst väljastatakse markdowni kohandatud konteineri stiilis.

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

Ülaltoodud tekst tõlgitakse HTML-is järgmiselt.

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

Koolonite arv on vaikimisi 7. Kui määrate koolonite järjestuse nagu C<:::::>, kasutatakse seda 7 kooloni asemel.

=item B<ifdef>

Algne ja teisendatud tekst trükitakse L<cpp(1)> C<#ifdef> formaadis.

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

Saate ainult jaapani teksti taastada käsuga B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Algne ja teisendatud tekst on trükitud ühe tühja reaga eraldatud. C<space+> puhul väljastab see ka uue rea pärast teisendatud teksti.

=item B<xtxt>

Kui formaat on C<xtxt> (tõlgitud tekst) või tundmatu, trükitakse ainult tõlgitud tekst.

=back

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

Määrake API-le korraga saadetava teksti maksimaalne pikkus. Vaikeväärtus on määratud nagu tasuta DeepL kontoteenuse puhul: 128K API jaoks (B<--xlate>) ja 5000 lõikelaua liidesele (B<--xlate-labor>). Saate neid väärtusi muuta, kui kasutate Pro teenust.

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

Määrake API-le korraga saadetava teksti maksimaalne ridade arv.

Määrake selle väärtuseks 1, kui soovite tõlkida ühe rea korraga. See valik on ülimuslik valikust C<--xlate-maxlen>.

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

Määrake tõlkemootorile saadetav kohandatud käsk. See valik on saadaval ainult ChatGPT-mootorite (gpt3, gpt4o, gpt5) kasutamisel. Võite kohandada tõlkimiskäitumist, andes AI-mudelile konkreetseid juhiseid. Kui käsk sisaldab C<%s>, asendatakse see sihtkeele nimega.

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

Määrake lisakonteksti teave, mis saadetakse tõlkemootorile. Seda valikut saab kasutada mitu korda, et anda mitu kontekstijada. Kontekstiandmed aitavad tõlkemootoril mõista tausta ja toota täpsemaid tõlkeid.

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

Määrake sõnastiku ID, mida kasutatakse tõlkimisel. See valik on saadaval ainult siis, kui kasutatakse DeepL mootorit. Sõnastiku ID tuleks saada teie DeepL kontolt ja see tagab konkreetsete terminite järjepideva tõlkimise.

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

Näete tõlkimise tulemust reaalajas STDERR-väljundist.

=item B<--xlate-stripe>

Kasutage L<App::Greple::stripe> moodulit, et näidata sobitatud osa sebratriibu moodi. See on kasulik siis, kui sobitatud osad on omavahel ühendatud.

Värvipalett vahetatakse vastavalt terminali taustavärvile. Kui soovite seda selgesõnaliselt määrata, võite kasutada B<--xlate-stripe-light> või B<--xlate-stripe-dark>.

=item B<--xlate-mask>

Sooritage maskeerimisfunktsioon ja kuvage teisendatud tekst sellisena, nagu see on, ilma taastamiseta.

=item B<--match-all>

Määrake kogu faili tekst sihtkohaks.

=item B<--lineify-cm>

=item B<--lineify-colon>

Formaatide C<cm> ja C<colon> puhul jagatakse ja vormistatakse väljund rida-realt. Seega, kui tõlgitakse ainult osa reast, ei saa oodatud tulemust. Need filtrid parandavad väljundi, mis on rikutud, kui osa reast tõlgitakse tavalise rea kaupa väljundiks.

Praeguses rakenduses, kui rea mitu osa tõlgitakse, väljastatakse need sõltumatute ridadega.

=back

=head1 CACHE OPTIONS

B<xlate> moodul võib salvestada iga faili tõlketeksti vahemällu ja lugeda seda enne täitmist, et kõrvaldada serveri küsimisega kaasnev koormus. Vaikimisi vahemälustrateegia C<auto> puhul säilitab ta vahemälu andmeid ainult siis, kui vahemälufail on sihtfaili jaoks olemas.

Kasutage B<--xlate-cache=clear>, et alustada vahemälu haldamist või puhastada kõik olemasolevad vahemälu andmed. Selle valikuga käivitamisel luuakse uus vahemälufail, kui seda ei ole veel olemas, ja seejärel hooldatakse seda automaatselt.

=over 7

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

=over 4

=item C<auto> (Default)

Säilitada vahemälufaili, kui see on olemas.

=item C<create>

Loob tühja vahemälufaili ja väljub.

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

Säilitab vahemälu andmed niikuinii, kui sihtfail on tavaline fail.

=item C<clear>

Tühjendage esmalt vahemälu andmed.

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

Ei kasuta kunagi vahemälufaili, isegi kui see on olemas.

=item C<accumulate>

Vaikimisi käitumise kohaselt eemaldatakse kasutamata andmed vahemälufailist. Kui te ei soovi neid eemaldada ja failis hoida, kasutage C<accumulate>.

=back

=item B<--xlate-update>

See valik sunnib uuendama vahemälufaili isegi siis, kui see pole vajalik.

=back

=head1 COMMAND LINE INTERFACE

Seda moodulit saab hõlpsasti kasutada käsurealt, kasutades jaotuses sisalduvat käsku C<xlate>. Kasutamise kohta vaata man-lehte C<xlate>.

Käsk C<xlate> toetab GNU stiilis pikki valikuid nagu C<--to-lang>, C<--from-lang>, C<--engine> ja C<--file>. Kasutage C<xlate -h>, et näha kõiki olemasolevaid valikuid.

C<xlate> käsk töötab koos Dockeri keskkonnaga, nii et isegi kui teil ei ole midagi paigaldatud, saate seda kasutada, kui Docker on saadaval. Kasutage valikut C<-D> või C<-C>.

Dockeri operatsioone käsitletakse L<App::dozo>, mida saab kasutada ka iseseisva käsuna. Käsk C<dozo> toetab C<.dozorc> konfiguratsioonifaili püsivate konteineri seadete jaoks.

Samuti, kuna makefile'id erinevate dokumendistiilide jaoks on olemas, on tõlkimine teistesse keeltesse võimalik ilma spetsiaalse täpsustuseta. Kasutage valikut C<-M>.

Saate ka kombineerida Dockeri ja C<make> valikuid, nii et saate käivitada C<make> Dockeri keskkonnas.

Käivitamine nagu C<xlate -C> käivitab shell'i, kuhu on paigaldatud praegune töötav git-repositoorium.

Lugege üksikasjalikult Jaapani artiklit L</SEE ALSO> osas.

=head1 EMACS

Laadige repositooriumis sisalduv fail F<xlate.el>, et kasutada C<xlate> käsku Emacs redaktorist. C<xlate-region> funktsioon tõlkida antud piirkonda. Vaikimisi keel on C<EN-US> ja te võite määrata keele, kutsudes seda prefix-argumendiga.

=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

Määrake oma autentimisvõti DeepL teenuse jaoks.

=item OPENAI_API_KEY

OpenAI autentimisvõti.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Peate installima käsurea tööriistad DeepL ja ChatGPT.

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

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

=head1 SEE ALSO

=head2 MODULES

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

L<App::dozo> - üldine Docker runner, mida xlate kasutab konteineroperatsioonideks.

=head2 RELATED MODULES

=over 2

=item * L<App::Greple>

Vt B<greple> käsiraamatust üksikasjalikult sihttekstimustri kohta. Kasutage B<--inside>, B<--outside>, B<--include>, B<--exclude> valikuid, et piirata sobitusala.

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

Saate kasutada C<-Mupdate> moodulit, et muuta faile B<greple> käsu tulemuse järgi.

=item * L<App::sdif>

Kasutage B<sdif>, et näidata konfliktimärkide formaati kõrvuti valikuga B<-V>.

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

Greple B<xlate-stripe> mooduli kasutamine B<--xlate-stripe> valikuga.

=back

=head2 RESOURCES

=over 2

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

Dockeri konteineri kujutis.

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

C<getoptlong.sh> raamatukogu, mida kasutatakse C<xlate> skripti ja L<App::dozo> valikute parsimiseks.

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

DeepL Pythoni raamatukogu ja CLI käsk.

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

OpenAI Pythoni raamatukogu

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

OpenAI käsurea liides

=back

=head2 ARTICLES

=over 2

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

Greple moodul tõlkida ja asendada ainult vajalikud osad DeepL API (jaapani keeles)

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

Dokumentide genereerimine 15 keeles DeepL API mooduliga (jaapani keeles).

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

Automaatne tõlkekeskkond Docker koos DeepL API-ga (jaapani keeles)

=back

=head1 AUTHOR

Kazumasa Utashiro

=head1 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.

=cut
