=encoding utf-8

=head1 NAME

App::Greple::xlate - vertaalondersteuningsmodule voor greple

=head1 SYNOPSIS

    greple -Mxlate -e ENGINE --xlate pattern target-file

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

=head1 VERSION

Version 0.9909

=head1 DESCRIPTION

Het B<Greple> B<xlate> module vindt gewenste tekstblokken en vervangt ze door de vertaalde tekst. Momenteel zijn de DeepL (F<deepl.pm>) en ChatGPT (F<gpt3.pm>) modules geïmplementeerd als back-end engine. Experimentele ondersteuning voor gpt-4 en gpt-4o is ook inbegrepen.

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

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

In deze opdracht betekent het patroonreeks C<^([\w\pP].*\n)+> opeenvolgende regels die beginnen met een alfanumeriek en leesteken. Deze opdracht toont het gebied dat vertaald moet worden 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. Het zal dan de gewenste secties vinden en ze vervangen door de uitvoer van het B<deepl> commando.

Standaard worden het oorspronkelijke en vertaalde tekst afgedrukt in het formaat van de "conflict marker" dat compatibel is met L<git(1)>. Met behulp van het C<ifdef> formaat kun je het gewenste deel krijgen met het L<unifdef(1)> commando. De uitvoerindeling 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 hele tekst wilt vertalen, gebruik dan de B<--match-all> optie. Dit is een snelkoppeling om het patroon C<(?s).+> te specificeren dat de hele tekst matcht.

Conflict marker formaatgegevens kunnen worden bekeken in een zij-aan-zij stijl met het C<sdif> commando met de C<-V> optie. Aangezien het geen zin heeft om op basis van elke string te vergelijken, wordt de C<--no-cdif> optie aanbevolen. Als je de tekst niet hoeft te kleuren, geef dan C<--no-textcolor> (of C<--no-tc>) op.

    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

Verwerking gebeurt in opgegeven eenheden, maar in het geval van een reeks van meerdere regels met 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 leesteken in volledige breedte, voeg dan samen met de volgende regel.

=item *

Als een regel eindigt met een volledig breedte karakter en de volgende regel begint met een volledig breedte karakter, voeg dan de regels samen.

=item *

Als het einde of het begin van een regel geen volledig breedte karakter is, voeg ze dan samen door een spatiekarakter in te voegen.

=back

Cachegegevens worden beheerd op basis van de genormaliseerde tekst, dus zelfs als er wijzigingen worden aangebracht die de normalisatieresultaten niet beïnvloeden, blijven de gecachte vertaalgegevens effectief.

Dit normalisatieproces wordt alleen uitgevoerd voor het eerste (0e) en even genummerde patroon. Als er dus twee patronen worden gespecificeerd zoals volgt, zal de tekst die overeenkomt met het eerste patroon worden verwerkt na normalisatie, en er zal geen normalisatieproces worden 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 tot één regel te combineren, en gebruik het tweede patroon voor vooraf opgemaakte tekst. Als er geen tekst is om overeen te komen met het eerste patroon, gebruik dan een patroon dat niets overeenkomt, zoals C<(?!)>.

=head1 MASKING

Af en toe zijn er delen van tekst die je niet vertaald wilt hebben. Bijvoorbeeld tags in markdown-bestanden. DeepL suggereert dat in dergelijke gevallen het te negeren deel van de tekst wordt omgezet naar XML-tags, vertaald en vervolgens wordt hersteld nadat de vertaling is voltooid. Om dit te ondersteunen, is het mogelijk om de delen die niet vertaald moeten worden te specificeren.

    --xlate-setopt maskfile=MASKPATTERN

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

Complex patroon kan worden geschreven op meerdere regels met een backslash geëscapete nieuwe regel.

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

Deze interface is experimenteel en kan in de toekomst worden gewijzigd.

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

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

Roep het vertaalproces aan voor elk overeenkomend gebied.

Zonder deze optie gedraagt B<greple> zich als een normaal zoekcommando. U kunt dus controleren welk deel van het bestand onderwerp zal zijn van de vertaling voordat u daadwerkelijk aan het werk gaat.

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

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

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

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

Specificeert de te gebruiken vertaalmotor. Als je de 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-turbo

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

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

=back

=item B<--xlate-labor>

=item B<--xlabor>

In plaats van de vertaalmotor aan te roepen, wordt er van jou verwacht dat je het werk doet. Nadat de tekst is voorbereid om te worden vertaald, wordt deze gekopieerd naar het klembord. Je wordt verwacht om 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. U kunt de beschikbare talen krijgen met het C<deepl languages> commando wanneer u de B<DeepL> motor gebruikt.

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

Specificeer het uitvoerformaat voor de oorspronkelijke 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, en 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)> conflict marker formaat.

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

U kunt het oorspronkelijke bestand herstellen met het volgende L<sed(1)> commando.

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

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

```html

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

<div style="background-color: #f4f4f4; color: #333; border-left: 6px solid #c0392b; padding: 10px; margin-bottom: 10px;">

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

Aantal dubbele punten is standaard 7. Als je een dubbele puntensequentie opgeeft zoals C<:::::>, wordt deze in plaats van 7 dubbele punten gebruikt.

=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

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

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Hello! How can I help you today?

=item B<xtxt>

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

=back

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

Vertaal de volgende tekst naar het Nederlands, regel voor regel.

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

Specificeer het maximale aantal regels tekst dat tegelijk naar de API wordt verzonden.

Stel deze waarde in op 1 als je regel voor regel wilt vertalen. Deze optie heeft voorrang op de C<--xlate-maxlen> optie.

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

Bekijk het vertaalresultaat in realtime in de STDERR-uitvoer.

=item B<--xlate-stripe>

Gebruik de L<App::Greple::stripe> module om het overeenkomende deel te tonen in een zebra-strepenpatroon. Dit is handig wanneer de overeenkomende delen aan elkaar zijn gekoppeld.

Het kleurenpalet wordt aangepast aan de achtergrondkleur van het terminal. Als je dit expliciet wilt specificeren, kun je B<--xlate-stripe-light> of B<--xlate-stripe-dark> gebruiken.

=item B<--xlate-mask>

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

=item B<--match-all>

Stel de volledige tekst van het bestand in als een doelgebied.

=back

=head1 CACHE OPTIONS

De B<xlate> module kan gecachte tekst van vertaling voor elk bestand opslaan en deze lezen vóór de uitvoering om de overhead van het vragen aan de server te elimineren. Met de standaard cache-strategie C<auto> wordt de cache alleen behouden wanneer het cachebestand bestaat voor het doelbestand.

Gebruik B<--xlate-cache=clear> om cachebeheer te starten of om alle bestaande cachegegevens op te schonen. Zodra dit met deze optie is uitgevoerd, wordt er een nieuw cachebestand aangemaakt als dat nog niet bestaat en vervolgens 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 stop.

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

Onderhoud de cache hoe dan ook zolang het doel een normaal bestand is.

=item C<clear>

Wis eerst de cachegegevens.

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

Gebruik nooit het cachebestand, zelfs als het bestaat.

=item C<accumulate>

Standaardgedrag is dat ongebruikte gegevens uit het cachebestand worden verwijderd. Als u ze niet wilt verwijderen en in het bestand wilt bewaren, gebruik dan C<accumulate>.

=back

=item B<--xlate-update>

Deze optie dwingt het bijwerken van het cachebestand af, zelfs als dit niet nodig is.

=back

=head1 COMMAND LINE INTERFACE

Je kunt dit module eenvoudig vanaf de commandoregel gebruiken door het C<xlate> commando te gebruiken dat is opgenomen in de distributie. Bekijk de C<xlate> man-pagina voor het gebruik.

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

Ook worden er makefiles geleverd voor verschillende documentstijlen, zodat vertalingen naar andere talen mogelijk zijn zonder speciale specificatie. Gebruik de C<-M> optie.

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

Als je het uitvoert zoals C<xlate -C>, wordt er een shell gestart met het huidige werkende git-repository gemount.

Lees het Japanse artikel in de L</ZIE OOK> sectie voor meer details.

=head1 EMACS

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

=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 command line tools installeren voor DeepL en 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>

Docker-containerbeeld.

=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 command line interface

=item * L<App::Greple>

Zie de handleiding van B<greple> voor meer informatie over het doelpatroon van de tekst. Gebruik de opties B<--inside>, B<--outside>, B<--include>, B<--exclude> om het overeenkomende gebied 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 B<greple> commando.

=item * L<App::sdif>

Gebruik B<sdif> om het conflictmarkeringsformaat zij aan zij weer te geven met de optie B<-V>.

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

Greple B<stripe> module gebruiken via 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>

Genereren van documenten in 15 talen met de DeepL API-module (in het Japans)

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

Automatische vertaling Docker-omgeving 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