=encoding utf-8

=head1 NAME

App::Greple::xlate - tõlke tugimoodul greple jaoks

=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> moodul leiab soovitud tekstiplokid ja asendab need tõlgitud tekstiga. Praegu on taustamootorina rakendatud DeepL (F<deepl.pm>), ChatGPT 4.1 (F<gpt4.pm>) ja GPT-5 (F<gpt5.pm>) moodulid.

Kui soovid tõlkida tavalisi tekstilõike dokumendis, mis on kirjutatud Perli pod-stiilis, kasuta B<greple> käsku koos C<xlate::deepl> ja C<perl> mooduliga järgmiselt:

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

Selles käsus tähendab mustristräng C<^([\w\pP].*\n)+> järjestikuseid ridu, mis algavad tähestiku- või kirjavahemärgiga. See käsk näitab tõlkimiseks valitud ala esile tõstetuna. Valikut B<--all> kasutatakse kogu teksti kuvamiseks.

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

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

Vaikimisi prinditakse originaal ja tõlgitud tekst "konfliktimarkeri" formaadis, mis on ühilduv L<git(1)>-ga. Kasutades C<ifdef> formaati, saad soovitud osa hõlpsasti kätte L<unifdef(1)> käsuga. Väljundvormingut saab määrata B<--xlate-format> valikuga.

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

Kui soovid tõlkida kogu teksti, kasuta B<--match-all> valikut. See on otsetee mustri C<(?s).+> määramiseks, mis sobib kogu tekstiga.

Konfliktimarkerite vormingut saab vaadata kõrvuti stiilis käsuga L<sdif|App::sdif> koos valikuga C<-V>. Kuna pole mõtet võrrelda stringi kaupa, on soovitatav kasutada valikut C<--no-cdif>. Kui teksti pole vaja värvida, määra 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 määratud ühikutes, kuid mitmest järjestikusest mittetühjast reast koosneva jada puhul teisendatakse need koos üheks reaks. See toiming toimub järgmiselt:

=over 2

=item *

Eemalda iga rea algusest ja lõpust tühikud.

=item *

Kui rida lõpeb täislaiuses kirjavahemärgiga, liida järgmise reaga.

=item *

Kui rida lõpeb täislaiuses märgiga ja järgmine rida algab täislaiuses märgiga, liida read kokku.

=item *

Kui kas rea lõpp või algus ei ole täislaiuses märk, liida need kokku, lisades tühiku.

=back

Vahemälus olevad andmed hallatakse normaliseeritud teksti põhjal, seega kui tehakse muudatusi, mis ei mõjuta normaliseerimise tulemust, jääb vahemällu salvestatud tõlge kehtima.

See normaliseerimisprotsess tehakse ainult esimesele (0.) ja paarisarvulisele mustrile. Seega, kui on määratud kaks mustrit järgmiselt, töödeldakse esimese mustriga sobiv tekst pärast normaliseerimist ja teise mustriga sobivale tekstile normaliseerimist ei rakendata.

    greple -Mxlate -E normalized -E not-normalized

Seetõttu kasuta esimest mustrit tekstile, mida töödeldakse mitme rea ühendamisel üheks reaks, ja teist mustrit eelvormindatud tekstile. Kui esimesele mustrile ei leidu sobivat teksti, kasuta mustrit, mis ei sobi millegagi, näiteks C<(?!)>.

=head1 MASKING

Aeg-ajalt on tekstis osi, mida te ei soovi tõlkida. Näiteks märgendid markdown-failides. DeepL soovitab sellistel juhtudel tõlkimisest välja jäetav osa muuta XML-märgenditeks, tõlkida ja seejärel pärast tõlkimist taastada. Selle toetamiseks on võimalik määrata osad, mida tõlkimisel maskeeritakse.

    --xlate-setopt maskfile=MASKPATTERN

See tõlgendab faili `MASKPATTERN` iga rida regulaaravaldisena, tõlgib sellele vastavad stringid ja taastab need pärast töötlemist. Ridasi, mis algavad C<#>-ga, ignoreeritakse.

Keerulisi mustreid saab kirjutada mitmele reale, kasutades tagasikaldkriipsuga reavahetust.

Kuidas tekst maskeerimise käigus muudetakse, saab näha B<--xlate-mask> valiku 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äivita tõlkeprotsess iga leitud ala kohta.

Ilma selle valikuta käitub B<greple> tavalise otsingukäsuna. Nii saad enne tegelikku tööd kontrollida, milline osa failist tõlkimisele allub.

Käsu tulemus läheb standardväljundisse, seega suuna vajadusel faili või kaalu L<App::Greple::update> mooduli kasutamist.

Valik B<--xlate> kutsub välja B<--xlate-color> valiku koos B<--color=never> valikuga.

Valikuga B<--xlate-fold> murdub teisendatud tekst määratud laiuse järgi. Vaikimisi laius on 70 ja seda saab määrata B<--xlate-fold-width> valikuga. Neli veergu on reserveeritud jooksva töö jaoks, seega mahub igale reale maksimaalselt 74 märki.

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

Määrab kasutatava tõlkemootori. Kui määrad mootorimooduli 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<gpt4>: gpt-4.1

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

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

=item * B<gpt5>: gpt-5

=back

=item B<--xlate-labor>

=item B<--xlabor>

Tõlkemootori kutsumise asemel eeldatakse, et töötad ise. Pärast tõlkimiseks vajaliku teksti ettevalmistamist kopeeritakse need lõikelauale. Eeldatakse, et kleebid need vormi, kopeerid tulemuse lõikelauale ja vajutad enter.

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

Määra sihtkeel. Saad saadaolevad keeled C<deepl languages> käsuga, kui kasutad B<DeepL> mootorit.

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

Määra originaal- ja tõlgitud teksti väljundvorming.

Järgnevad vormingud peale C<xtxt> eeldavad, et tõlgitav osa on ridade kogum. Tegelikult on võimalik tõlkida ainult osa reast, kuid muu kui C<xtxt> vormingu määramine ei anna mõistlikku tulemust.

=over 4

=item B<conflict>, B<cm>

Originaal- ja teisendatud tekst trükitakse L<git(1)> konflikti markerite vormingus.

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

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

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

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

Originaal- ja tõlgitud tekst väljastatakse markdown'i 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äärad koolonite jada nagu C<:::::>, kasutatakse seda 7 asemel.

=item B<ifdef>

Originaal- ja teisendatud tekst trükitakse L<cpp(1)> C<#ifdef> vormingus.

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

Ainult jaapanikeelse teksti saab kätte B<unifdef> käsuga:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Originaal- ja teisendatud tekst prinditakse välja ühe tühja reaga eraldatult. C<space+> puhul lisatakse teisendatud teksti järel ka reavahetus.

=item B<xtxt>

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

=back

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

Määra maksimaalne tekstipikkus, mida API-le korraga saata. Vaikeväärtus on seatud tasuta DeepL konto teenuse jaoks: 128K API jaoks (B<--xlate>) ja 5000 lõikepuhvri liidese jaoks (B<--xlate-labor>). Võid neid väärtusi muuta, kui kasutad Pro teenust.

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

Määra maksimaalne ridade arv, mida API-le korraga saata.

Sea see väärtus 1-le, kui soovid tõlkida ühe rea korraga. See valik on prioriteetsem kui C<--xlate-maxlen> valik.

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

Määra kohandatud viip, mis saadetakse tõlkemootorile. See valik on saadaval ainult ChatGPT mootorite (gpt3, gpt4, gpt4o) kasutamisel. Saad tõlke käitumist kohandada, andes AI-mudelile konkreetseid juhiseid. Kui viip sisaldab C<%s>, asendatakse see sihtkeele nimega.

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

Määra täiendav kontekstiteave, mis saadetakse tõlkemootorile. Seda valikut saab kasutada mitu korda, et anda mitu kontekstistringi. Kontekstiteave aitab tõlkemootoril mõista tausta ja toota täpsemaid tõlkeid.

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

Määra tõlkes kasutatav sõnastiku ID. See valik on saadaval ainult DeepL mootori kasutamisel. Sõnastiku ID tuleb hankida oma DeepL kontolt ning see tagab kindlate terminite järjepideva tõlkimise.

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

Vaata tõlketulemust reaalajas STDERR väljundis.

=item B<--xlate-stripe>

Kasuta L<App::Greple::stripe> moodulit, et näidata sobivat osa sebramustriga. See on kasulik, kui sobivad osad on järjestikku ühendatud.

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

=item B<--xlate-mask>

Tee maskimisfunktsioon ja kuva teisendatud tekst muutmata kujul.

=item B<--match-all>

Määra kogu faili tekst sihtalaks.

=item B<--lineify-cm>

=item B<--lineify-colon>

C<cm> ja C<colon> vormingute puhul jagatakse väljund ja vormindatakse rida-realt. Seetõttu, kui ainult osa reast tõlgitakse, ei saa oodatud tulemust. Need filtrid parandavad väljundi, mis on rikutud, tõlkides osa reast normaalseks rida-realt väljundiks.

Praeguses teostuses, kui mitu osa reast tõlgitakse, väljastatakse need iseseisvate ridadena.

=back

=head1 CACHE OPTIONS

B<xlate> moodul saab salvestada iga faili tõlke vahemällu ja lugeda selle enne täitmist, et vältida serverilt pärimise viivitust. Vaikimisi vahemälustrateegia C<auto> korral hoitakse vahemälu ainult siis, kui sihtfaili jaoks on olemas vahemälufail.

Kasuta B<--xlate-cache=clear> vahemälu haldamise alustamiseks või kõigi olemasolevate vahemäluandmete puhastamiseks. Kui see valik on korra käivitatud, luuakse uus vahemälufail, kui seda veel pole, ja seda hallatakse automaatselt edasi.

=over 7

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

=over 4

=item C<auto> (Default)

Halda vahemälufaili, kui see eksisteerib.

=item C<create>

Loo tühi vahemälufail ja välju.

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

Halda vahemälu igal juhul, kui sihtfail on tavaline fail.

=item C<clear>

Kustuta kõigepealt vahemälu andmed.

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

Ära kasuta kunagi vahemälufaili, isegi kui see eksisteerib.

=item C<accumulate>

Vaikimisi eemaldatakse kasutamata andmed vahemälufailist. Kui sa ei soovi neid eemaldada ja tahad alles hoida, kasuta C<accumulate>.

=back

=item B<--xlate-update>

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

=back

=head1 COMMAND LINE INTERFACE

Seda moodulit saab hõlpsasti käsurealt kasutada, kasutades distributsiooniga kaasas olevat C<xlate> käsku. Kasutamiseks vaata C<xlate> manuaalilehte.

C<xlate> käsk toetab GNU-stiilis pikki valikuid nagu C<--to-lang>, C<--from-lang>, C<--engine> ja C<--file>. Kõigi saadaolevate valikute nägemiseks kasuta C<xlate -h>.

Käsk C<xlate> töötab koos Dockeriga, nii et isegi kui sul pole midagi paigaldatud, saad seda kasutada, kui Docker on saadaval. Kasuta C<-D> või C<-C> valikut.

Dockeri toiminguid haldab C<xrun> skript, mida saab kasutada ka iseseisva käsuna. C<xrun> skript toetab C<.xrunrc> seadistusfaili püsivate konteineriseadete jaoks.

Kuna on olemas erinevate dokumendistiilide makefile'id, on võimalik tõlkida ka teistesse keeltesse ilma erilise määratluseta. Kasuta C<-M> valikut.

Samuti saad kombineerida Dockerit ja C<make> valikut, et käivitada C<make> Docker-keskkonnas.

Käivitades näiteks C<xlate -C> avatakse shell, kus on ühendatud praegune töötav git-hoidla.

Loe jaapani keeles artiklit L</SEE ALSO> jaotises üksikasjade kohta.

=head1 EMACS

Laadi hoidlas olev F<xlate.el> fail, et kasutada C<xlate> käsku Emacsi redaktoris. C<xlate-region> funktsioon tõlgib määratud piirkonna. Vaikimisi keel on C<EN-US> ja vajadusel saad keelt määrata, andes ette prefiksi argumendi.

=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äära oma DeepL teenuse autentimisvõti.

=item OPENAI_API_KEY

OpenAI autentimisvõti.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Pead paigaldama käsurea tööriistad DeepL-i ja ChatGPT jaoks.

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::gpt4>

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

=over 2

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

Dockeri konteineri kujutis.

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

C<getoptlong.sh> teek, mida kasutatakse valikute parsimiseks C<xlate> ja C<xrun> skriptides.

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

DeepL-i Pythoni teek ja CLI käsk.

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

OpenAI Pythoni teek

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

OpenAI käsurea liides

=item * L<App::Greple>

Vaata B<greple> juhendit, et saada täpsemat teavet sihtteksti mustri kohta. Kasuta B<--inside>, B<--outside>, B<--include>, B<--exclude> valikuid, et piirata sobitamise ala.

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

Saad kasutada C<-Mupdate> moodulit, et muuta faile B<greple> käsu tulemuste põhjal.

=item * L<App::sdif>

Kasuta B<sdif> valikut, et kuvada konfliktimärgendite vormingut kõrvuti koos B<-V> valikuga.

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

Greple B<stripe> moodulit kasutatakse B<--xlate-stripe> valikuga.

=back

=head2 ARTICLES

=over 2

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

Greple moodul, mis tõlgib ja asendab ainult vajalikud osad DeepL API abil (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õlke Dockeri keskkond DeepL API-ga (jaapani keeles)

=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
