=encoding utf-8

=head1 NAME

App::Greple::xlate - vertaalondersteuningsmodule voor greple

=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> module vindt de gewenste tekstblokken en vervangt deze door de vertaalde tekst. Momenteel zijn DeepL (F<deepl.pm>), ChatGPT 4.1 (F<gpt4.pm>) en GPT-5 (F<gpt5.pm>) modules geïmplementeerd als back-end engine.

Als je normale tekstblokken in een document geschreven in de Perl's pod-stijl wilt vertalen, gebruik dan het B<greple> commando met 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 een alfanumeriek teken of leesteken. 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 C<--xlate> optie 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 het C<ifdef> formaat kun je het gewenste deel eenvoudig verkrijgen met het L<unifdef(1)> commando. Het uitvoerformaat kan worden gespecificeerd met de B<--xlate-format> optie.

=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 B<--match-all> optie. Dit is een snelkoppeling om het patroon C<(?s).+> te specificeren dat overeenkomt met de volledige tekst.

Conflictmarkeringformaatgegevens kunnen in zij-aan-zij stijl worden bekeken met het L<sdif|App::sdif> commando met de C<-V> optie. Aangezien het geen zin heeft om per tekenreeks te vergelijken, wordt de C<--no-cdif> optie aanbevolen. Als u de tekst niet hoeft te kleuren, geef dan C<--no-textcolor> (of C<--no-tc>) op.

    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 opgegeven eenheden, maar in het geval van een reeks van meerdere regels niet-lege tekst, worden deze 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 volbreedte leesteken, voeg samen met de volgende regel.

=item *

Als een regel eindigt met een volbreedte teken en de volgende regel begint met een volbreedte teken, voeg de regels samen.

=item *

Als het einde of het begin van een regel geen volbreedte teken is, voeg ze dan samen door een spatie toe te voegen.

=back

Cachegegevens worden beheerd op basis van de genormaliseerde tekst, dus zelfs als er wijzigingen worden aangebracht die geen invloed hebben op het normalisatieresultaat, blijft de vertaalde cachegegevens 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 normalisatie 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 samen te voegen 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

Af en toe zijn er delen van tekst die je niet wilt vertalen. Bijvoorbeeld, tags in markdown-bestanden. DeepL stelt voor om in zulke gevallen het te vertalen deel om te zetten naar XML-tags, te vertalen, en daarna na de vertaling te herstellen. Om dit te ondersteunen, is het mogelijk om de delen die van vertaling uitgesloten moeten worden, te specificeren.

    --xlate-setopt maskfile=MASKPATTERN

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

Complexe patronen kunnen over meerdere regels worden geschreven met een backslash-escaped nieuwe regel.

Hoe de tekst wordt getransformeerd door maskering kan worden bekeken met de B<--xlate-mask> optie.

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 vertaling zal zijn voordat je het daadwerkelijke werk uitvoert.

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

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

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

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

Specificeert de te gebruiken vertaalmachine. Als je het engine-module 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<gpt4>: gpt-4.1

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

B<gpt-4o>'s interface is instabiel en kan momenteel niet gegarandeerd correct werken.

=item * B<gpt5>: gpt-5

=back

=item B<--xlate-labor>

=item B<--xlabor>

In plaats van de vertaalmachine aan te roepen, wordt van je verwacht dat je het werk uitvoert. Nadat de te vertalen tekst is voorbereid, worden ze naar het klembord gekopieerd. Je wordt geacht ze in het formulier te plakken, het resultaat naar het klembord te kopiëren en op enter te drukken.

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

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

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

Specificeer het uitvoerformaat voor originele en vertaalde tekst.

De volgende formaten anders dan C<xtxt> gaan ervan uit dat het te vertalen deel een verzameling regels is. In feite is het mogelijk om slechts een deel van een regel te vertalen, maar het specificeren van een ander formaat dan C<xtxt> zal geen zinvolle resultaten opleveren.

=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 L<sed(1)> commando.

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

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

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

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

Bovenstaande tekst wordt als volgt vertaald naar HTML.

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

Het aantal dubbele punten is standaard 7. Als je een dubbelepuntreeks opgeeft zoals C<:::::>, wordt deze 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 B<unifdef> commando:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Originele en geconverteerde tekst worden afgedrukt, gescheiden door een enkele lege regel.

=item B<xtxt>

Voor C<space+> wordt er ook een nieuwe regel na de geconverteerde tekst toegevoegd.

=back

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

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

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

Specificeer de maximale lengte van de tekst die in één keer naar de API mag worden gestuurd. De 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 waarde wijzigen als u de Pro-service gebruikt.

Specificeer het maximaal aantal regels tekst dat in één keer naar de API mag worden gestuurd.

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

Geef een aangepaste prompt op die naar de vertaalmachine wordt gestuurd. Deze optie is alleen beschikbaar bij gebruik van ChatGPT-engines (gpt3, gpt4, gpt4o). Je kunt het vertaalgedrag aanpassen door specifieke instructies aan het AI-model te geven. Als de prompt C<%s> bevat, wordt deze 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 de vertaling wordt gebruikt. Deze optie is alleen beschikbaar bij gebruik van de DeepL-engine. De woordenlijst-ID moet uit je DeepL-account worden verkregen en zorgt voor consistente vertaling van specifieke termen.

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

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

=item B<--xlate-stripe>

Bekijk het vertaalresultaat in realtime in de STDERR-uitvoer.

Gebruik de L<App::Greple::stripe>-module om het overeenkomende gedeelte in zebra-streepjesstijl weer te geven. Dit is handig wanneer de overeenkomende delen direct aan elkaar zijn gekoppeld.

=item B<--xlate-mask>

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

=item B<--match-all>

Voer de maskeringsfunctie uit en toon de geconverteerde tekst zoals deze is, zonder herstel.

=item B<--lineify-cm>

=item B<--lineify-colon>

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

In de huidige implementatie worden meerdere vertaalde delen van een regel als onafhankelijke regels weergegeven.

=back

=head1 CACHE OPTIONS

Stel de volledige tekst van het bestand in als doelgebied.

De B<xlate>-module kan gecachte vertaalde tekst per bestand opslaan en deze vóór uitvoering lezen om de overhead van het opvragen bij de server te elimineren. Met de standaard cache-strategie C<auto> wordt cachedata alleen onderhouden als het cachebestand voor het doelbestand bestaat.

=over 7

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

=over 4

=item C<auto> (Default)

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

=item C<create>

Onderhoud het cachebestand als het bestaat.

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

Maak een leeg cachebestand aan en sluit af.

=item C<clear>

Onderhoud de cache in ieder geval zolang het doel een normaal bestand is.

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

Wis eerst de cachedata.

=item C<accumulate>

Gebruik nooit een cachebestand, zelfs niet als het bestaat.

=back

=item B<--xlate-update>

Standaard wordt ongebruikte data uit het cachebestand verwijderd. Als u deze niet wilt verwijderen en in het bestand wilt houden, gebruik dan C<accumulate>.

=back

=head1 COMMAND LINE INTERFACE

Met deze optie wordt het cachebestand geforceerd bijgewerkt, zelfs als dit niet nodig is.

Het C<xlate> commando 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.

U kunt deze module eenvoudig vanaf de opdrachtregel gebruiken met het C<xlate>-commando dat bij de distributie is inbegrepen. Zie de C<xlate>-manpagina voor gebruik.

Docker-bewerkingen worden afgehandeld door het C<xrun> script, dat ook als een zelfstandige opdracht kan worden gebruikt. Het C<xrun> script ondersteunt het C<.xrunrc> configuratiebestand voor persistente containerinstellingen.

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

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

U kunt ook de Docker- en C<make>-opties combineren, zodat u C<make> in een Docker-omgeving kunt uitvoeren.

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

=head1 EMACS

Laad het F<xlate.el> bestand dat in de repository is opgenomen om het C<xlate> commando vanuit de Emacs-editor te gebruiken. C<xlate-region> functie vertaalt het opgegeven gebied. De standaardtaal is C<EN-US> en je kunt de taal specificeren 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 voor de DeepL-service in.

=item OPENAI_API_KEY

OpenAI authenticatiesleutel.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Je moet de commandoregeltools voor DeepL en ChatGPT installeren.

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>

Docker container image.

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

De C<getoptlong.sh> bibliotheek wordt gebruikt voor optieparsing in de C<xlate> en C<xrun> scripts.

=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

=item * L<App::Greple>

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

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

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

=item * L<App::sdif>

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

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

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

=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-Dockeromgeving met DeepL API (in het Japans)

=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
