=encoding utf-8

=head1 NAME

App::Greple::xlate - vertaalondersteuningsmodule voor greple

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

=head1 DESCRIPTION

B<Greple> B<xlate>-module vindt gewenste tekstblokken en vervangt ze door de vertaalde tekst. Momenteel zijn DeepL (F<deepl.pm>) en de GPT-5.5 (F<gpt5.pm>)-module geïmplementeerd als back-end-engine.

Als je normale tekstblokken in een document in Perl's pod-stijl wilt vertalen, gebruik dan het B<greple>-commando met de C<xlate::deepl>- en C<perl>-module zoals dit:

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

In dit commando betekent de patroonstring C<^([\w\pP].*\n)+> opeenvolgende regels die beginnen met alfanumerieke en leestekens. Dit commando toont het te vertalen gebied gemarkeerd. Optie B<--all> wordt gebruikt om de volledige tekst te produceren.

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

Voeg vervolgens de optie C<--xlate> toe om het geselecteerde gebied te vertalen. Dan worden de gewenste secties gevonden en vervangen door de uitvoer van het B<deepl>-commando.

Standaard worden originele en vertaalde tekst afgedrukt in het "conflict marker"-formaat dat compatibel is met L<git(1)>. Met C<ifdef>-formaat kun je het gewenste deel gemakkelijk verkrijgen met het L<unifdef(1)>-commando. Het uitvoerformaat kan worden gespecificeerd met de optie 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>

Als je de volledige tekst wilt vertalen, gebruik dan de optie B<--match-all>. Dit is een snelkoppeling om het patroon C<(?s).+> op te geven dat overeenkomt met de volledige tekst.

Gegevens in conflict marker-formaat kunnen in zij-aan-zij-stijl worden bekeken met het L<sdif|App::sdif>-commando met optie C<-V>. Aangezien het geen zin heeft om per string te vergelijken, wordt de optie C<--no-cdif> aanbevolen. Als je de tekst niet hoeft te kleuren, specificeer C<--no-textcolor> (of 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

De verwerking gebeurt in gespecificeerde eenheden, maar in het geval van een reeks van meerdere regels niet-lege tekst worden ze samen omgezet in één regel. Deze bewerking wordt als volgt uitgevoerd:

=over 2

=item *

Verwijder witruimte aan het begin en einde van elke regel.

=item *

Als een regel eindigt met een full-width leesteken, concateneer met de volgende regel.

=item *

Als een regel eindigt met een full-width teken en de volgende regel begint met een full-width teken, concateneer de regels.

=item *

Als het einde of het begin van een regel geen full-width teken is, concateneer ze door een spatie in te voegen.

=back

Cachegegevens worden beheerd op basis van de genormaliseerde tekst, dus zelfs als wijzigingen worden aangebracht die de normalisatieresultaten niet beïnvloeden, blijft de vertaalde cachedata effectief.

Dit normalisatieproces wordt alleen uitgevoerd voor het eerste (0e) en even genummerde patroon. Dus als twee patronen als volgt worden opgegeven, wordt de tekst die overeenkomt met het eerste patroon verwerkt na normalisatie, en wordt er geen normalisatieproces uitgevoerd op de tekst die overeenkomt met het tweede patroon.

    greple -Mxlate -E normalized -E not-normalized

Gebruik daarom het eerste patroon voor tekst die moet worden verwerkt door meerdere regels te combineren tot één regel, en gebruik het tweede patroon voor vooraf opgemaakte tekst. Als er geen tekst is die overeenkomt met het eerste patroon, gebruik dan een patroon dat nergens mee overeenkomt, zoals C<(?!)>.

=head1 MASKING

Soms zijn er delen van de tekst die je niet wilt vertalen. Bijvoorbeeld tags in markdown-bestanden. DeepL stelt voor om in dergelijke gevallen het te uitsluiten deel van de tekst om te zetten naar XML-tags, te vertalen en daarna na voltooiing van de vertaling te herstellen. Ter ondersteuning hiervan is het mogelijk om de delen die van vertaling moeten worden gemaskeerd op te geven.

    --xlate-setopt maskfile=MASKPATTERN

Dit zal elke regel van het bestand C<MASKPATTERN> interpreteren als een reguliere expressie, strings die ermee overeenkomen vertalen en terugdraaien na verwerking. Regels die beginnen met C<#> worden genegeerd.

Een complex patroon kan over meerdere regels worden geschreven met een backslash-geëscapete regeleinde.

Hoe de tekst door maskering wordt getransformeerd, is te zien met de optie B<--xlate-mask>.

Deze interface is experimenteel en kan in de toekomst veranderen.

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

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

Start het vertaalproces voor elk overeenkomend gebied.

Zonder deze optie gedraagt B<greple> zich als een normale zoekopdracht. Zo kun je controleren welk deel van het bestand onderwerp van de vertaling zal zijn voordat je het echte werk start.

Het commandoresultaat gaat naar standaarduitvoer, dus leid indien nodig om naar een bestand, of overweeg het gebruik van de module L<App::Greple::update>.

Optie B<--xlate> roept optie B<--xlate-color> aan met optie B<--color=never>.

Met optie B<--xlate-fold> wordt geconverteerde tekst opgevouwen tot de opgegeven breedte. De standaardbreedte is 70 en kan worden ingesteld met optie B<--xlate-fold-width>. Er zijn vier kolommen gereserveerd voor run-in-bewerking, dus elke regel kan maximaal 74 tekens bevatten.

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

Specificeert de te gebruiken vertaalengine. Als je de enginemodule direct specificeert, zoals C<-Mxlate::deepl>, hoef je deze optie niet te gebruiken.

Op dit moment zijn de volgende engines beschikbaar

=over 2

=item * B<deepl>: DeepL API

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

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

De interface van B<gpt-4o> is instabiel en kan op dit moment niet gegarandeerd correct werken.

=item * B<gpt5>: gpt-5.5

=back

=item B<--xlate-labor>

=item B<--xlabor>

In plaats van de vertaalengine aan te roepen, wordt verwacht dat jij het werk doet. Na het voorbereiden van de te vertalen tekst worden deze naar het klembord gekopieerd. Je wordt verondersteld ze in het formulier te plakken, het resultaat naar het klembord te kopiëren en op return te drukken.

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

Specificeer de doeltaal. Je kunt beschikbare talen opvragen met het commando C<deepl languages> wanneer je de engine B<DeepL> gebruikt.

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

Specificeer de uitvoerindeling voor originele en vertaalde tekst.

De volgende indelingen, anders dan C<xtxt>, gaan ervan uit dat het te vertalen deel een verzameling regels is. In feite is het mogelijk slechts een gedeelte van een regel te vertalen, maar het specificeren van een andere indeling dan C<xtxt> levert geen zinvol resultaat op.

=over 4

=item B<conflict>, B<cm>

Originele en geconverteerde tekst worden afgedrukt in L<git(1)>-conflictmarkeringsformaat.

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

Je kunt het originele bestand herstellen met het volgende commando L<sed(1)>.

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

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

De originele en vertaalde tekst worden uitgevoerd in een aangepaste containerstijl van markdown.

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

Bovenstaande tekst wordt in HTML als volgt vertaald.

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

Het aantal dubbele punten is standaard 7. Als je een reeks dubbele punten opgeeft zoals C<:::::>, wordt die gebruikt in plaats van 7 dubbele punten.

=item B<ifdef>

Originele en geconverteerde tekst worden afgedrukt in L<cpp(1)> C<#ifdef>-formaat.

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

Je kunt alleen Japanse tekst ophalen met het commando B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Originele en geconverteerde tekst worden afgedrukt, gescheiden door één lege regel. Voor C<space+> wordt ook een regeleinde na de geconverteerde tekst uitgegeven.

=item B<xtxt>

Als het formaat C<xtxt> (vertaalde tekst) is of onbekend, wordt alleen de vertaalde tekst afgedrukt.

=back

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

Geef de maximale lengte op van tekst die in één keer naar de API wordt verzonden. Standaardwaarde is ingesteld zoals voor de gratis DeepL-accountservice: 128K voor de API (B<--xlate>) en 5000 voor de klembordinterface (B<--xlate-labor>). Mogelijk kunt u deze waarden wijzigen als u de Pro-service gebruikt.

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

Geef het maximale aantal regels tekst op dat in één keer naar de API wordt verzonden.

Stel deze waarde in op 1 als u één regel per keer wilt vertalen. Deze optie heeft voorrang op de optie C<--xlate-maxlen>.

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

Geef een aangepaste prompt op die naar de vertaalengine wordt gestuurd. Deze optie is alleen beschikbaar bij gebruik van ChatGPT-engines (gpt3, gpt4o, gpt5). U kunt het vertaalgedrag aanpassen door specifieke instructies aan het AI-model te geven. Als de prompt C<%s> bevat, wordt dit vervangen door de naam van de doeltaal.

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

Geef extra contextinformatie op die naar de vertaalmachine wordt gestuurd. Deze optie kan meerdere keren worden gebruikt om meerdere contextstrings te leveren. De contextinformatie helpt de vertaalmachine de achtergrond te begrijpen en nauwkeurigere vertalingen te produceren.

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

Geef een woordenlijst-ID op die voor vertaling wordt gebruikt. Deze optie is alleen beschikbaar bij gebruik van de DeepL-engine. De woordenlijst-ID moet uit uw DeepL-account worden verkregen en zorgt voor consistente vertaling van specifieke termen.

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

Bekijk het vertaalresultaat in realtime in de STDERR-uitvoer.

=item B<--xlate-stripe>

Gebruik de module L<App::Greple::stripe> om het overeenkomende deel te tonen met zebra-achtige arcering. Dit is handig wanneer de overeenkomende delen rug-aan-rug zijn verbonden.

Het kleurenpalet wordt geschakeld volgens de achtergrondkleur van de terminal. Als u het expliciet wilt opgeven, kunt u B<--xlate-stripe-light> of B<--xlate-stripe-dark> gebruiken.

=item B<--xlate-mask>

Voer de maskeringsfunctie uit en geef de geconverteerde tekst weer zoals die is, zonder herstel.

=item B<--match-all>

Stel de volledige tekst van het bestand in als doelgebied.

=item B<--lineify-cm>

=item B<--lineify-colon>

In het geval van de formaten C<cm> en C<colon> wordt de output gesplitst en regel voor regel opgemaakt. Daarom kan, als slechts een deel van een regel moet worden vertaald, het verwachte resultaat niet worden verkregen. Deze filters herstellen output die is beschadigd door het vertalen van een deel van een regel naar normale, regel-voor-regel output.

In de huidige implementatie worden, als meerdere delen van een regel worden vertaald, deze als zelfstandige regels uitgegeven.

=back

=head1 CACHE OPTIONS

De module B<xlate> kan gecachete vertalingstekst per bestand opslaan en vóór uitvoering inlezen om de overhead van het vragen aan de server te elimineren. Met de standaardcache-strategie C<auto> wordt cachedata alleen onderhouden wanneer het cachebestand voor het doelfile bestaat.

Gebruik B<--xlate-cache=clear> om cachebeheer te initiëren of om alle bestaande cachedata op te schonen. Na eenmaal met deze optie te zijn uitgevoerd, wordt een nieuw cachebestand aangemaakt als er nog geen bestaat en daarna automatisch onderhouden.

=over 7

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

=over 4

=item C<auto> (Default)

Onderhoud het cachebestand als het bestaat.

=item C<create>

Maak een leeg cachebestand aan en sluit af.

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

Houd de cache toch bij zolang het doel een normaal bestand is.

=item C<clear>

Maak eerst de cachedata leeg.

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

Gebruik nooit een cachebestand, zelfs niet als het bestaat.

=item C<accumulate>

Standaard worden ongebruikte gegevens uit het cachebestand verwijderd. Als je ze niet wilt verwijderen en in het bestand wilt houden, gebruik dan C<accumulate>.

=back

=item B<--xlate-update>

Deze optie dwingt een update van het cachebestand af, zelfs als dat niet nodig is.

=back

=head1 COMMAND LINE INTERFACE

Je kunt deze module eenvoudig vanaf de commandoregel gebruiken met het commando C<xlate> dat in de distributie is opgenomen. Zie de man-pagina C<xlate> voor gebruik.

De C<xlate>-opdracht ondersteunt GNU-stijl lange opties zoals C<--to-lang>, C<--from-lang>, C<--engine> en C<--file>. Gebruik C<xlate -h> om alle beschikbare opties te zien.

Het commando C<xlate> werkt samen met de Docker-omgeving, dus ook als je niets lokaal hebt geïnstalleerd, kun je het gebruiken zolang Docker beschikbaar is. Gebruik de optie C<-D> of C<-C>.

Docker-bewerkingen worden afgehandeld door L<App::dozo>, dat ook als zelfstandige opdracht kan worden gebruikt. De opdracht C<dozo> ondersteunt het configuratiebestand C<.dozorc> voor persistente containerinstellingen.

Omdat makefiles voor verschillende documentstijlen worden meegeleverd, is vertalen naar andere talen mogelijk zonder speciale specificatie. Gebruik de optie C<-M>.

Je kunt ook de Docker- en C<make>-opties combineren zodat je C<make> in een Docker-omgeving kunt uitvoeren.

Uitvoeren zoals C<xlate -C> start een shell met de huidige werkende git-repository gemount.

Lees het Japanse artikel in de sectie L</SEE ALSO> voor details.

=head1 EMACS

Laad het bestand F<xlate.el> in de repository om het commando C<xlate> vanuit de Emacs-editor te gebruiken. De functie C<xlate-region> vertaalt de opgegeven regio. De standaardtaal is C<EN-US> en je kunt een taal opgeven door het met een prefix-argument aan te roepen.

=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

Stel je authenticatiesleutel in voor de DeepL-service.

=item OPENAI_API_KEY

OpenAI-authenticatiesleutel.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Je moet commandoregelhulpmiddelen voor DeepL en ChatGPT installeren.

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> - Generieke Docker-runner die door xlate wordt gebruikt voor containeroperaties

=head2 RELATED MODULES

=over 2

=item * L<App::Greple>

Zie de handleiding B<greple> voor details over het doelsjabloon. Gebruik de opties B<--inside>, B<--outside>, B<--include>, B<--exclude> om het matchgebied te beperken.

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

Je kunt de module C<-Mupdate> gebruiken om bestanden te wijzigen op basis van het resultaat van het commando B<greple>.

=item * L<App::sdif>

Gebruik B<sdif> om het conflictmarkeerformaat naast elkaar te tonen met de optie B<-V>.

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

Greple B<stripe>-module gebruikt met de optie B<--xlate-stripe>.

=back

=head2 RESOURCES

=over 2

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

Docker-containerimage.

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

De bibliotheek C<getoptlong.sh> die wordt gebruikt voor het parseren van opties in het script C<xlate> en L<App::dozo>.

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

DeepL Python-bibliotheek en CLI-commando.

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

OpenAI Python-bibliotheek

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

OpenAI commandoregelinterface

=back

=head2 ARTICLES

=over 2

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

Greple-module om alleen de noodzakelijke delen te vertalen en te vervangen met de DeepL-API (in het Japans)

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

Documenten genereren in 15 talen met de DeepL-API-module (in het Japans)

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

Automatische vertaal-Docker-omgeving met DeepL-API (in het Japans)

=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
