=encoding utf-8

=head1 NAME

App::Greple::xlate - module de support de traduction pour greple  

=head1 SYNOPSIS

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

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

=head1 VERSION

Version 0.9908

=head1 DESCRIPTION

B<Greple> B<xlate> module trouve les blocs de texte souhaités et les remplace par le texte traduit. Actuellement, les modules DeepL (F<deepl.pm>) et ChatGPT (F<gpt3.pm>) sont implémentés comme moteur de back-end. Un support expérimental pour gpt-4 et gpt-4o est également inclus.  

Si vous souhaitez traduire des blocs de texte normaux dans un document écrit dans le style pod de Perl, utilisez la commande B<greple> avec C<xlate::deepl> et le module C<perl> comme ceci :  

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

Dans cette commande, la chaîne de motif C<^([\w\pP].*\n)+> signifie des lignes consécutives commençant par une lettre alphanumérique et de ponctuation. Cette commande montre la zone à traduire mise en surbrillance. L'option B<--all> est utilisée pour produire l'intégralité du texte.

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

Ajoutez ensuite l'option C<--xlate> pour traduire la zone sélectionnée. Ensuite, il trouvera les sections souhaitées et les remplacera par la sortie de la commande B<deepl>.  

Par défaut, le texte original et le texte traduit sont imprimés au format "marqueur de conflit" compatible avec L<git(1)>. En utilisant le format C<ifdef>, vous pouvez obtenir la partie souhaitée facilement avec la commande L<unifdef(1)>. Le format de sortie peut être spécifié par l'option 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>

Si vous souhaitez traduire l'intégralité du texte, utilisez l'option B<--match-all>. C'est un raccourci pour spécifier le motif C<(?s).+> qui correspond à l'intégralité du texte.  

Les données au format de marqueur de conflit peuvent être visualisées en style côte à côte avec la commande C<sdif> et l'option C<-V>. Comme il n'est pas logique de comparer sur une base de chaîne par chaîne, l'option C<--no-cdif> est recommandée. Si vous n'avez pas besoin de colorer le texte, spécifiez C<--no-textcolor> (ou C<--no-tc>).  

    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

Le traitement est effectué en unités spécifiées, mais dans le cas d'une séquence de plusieurs lignes de texte non vide, elles sont converties ensemble en une seule ligne. Cette opération est effectuée comme suit :  

=over 2

=item *

Supprimez les espaces blancs au début et à la fin de chaque ligne.  

=item *

Si une ligne se termine par un caractère de ponctuation à largeur complète, concaténez-la avec la ligne suivante.  

=item *

Si une ligne se termine par un caractère à largeur complète et que la ligne suivante commence par un caractère à largeur complète, concaténez les lignes.  

=item *

Si la fin ou le début d'une ligne n'est pas un caractère à largeur complète, concaténez-les en insérant un caractère d'espace.  

=back

Les données de cache sont gérées en fonction du texte normalisé, donc même si des modifications sont apportées qui n'affectent pas les résultats de normalisation, les données de traduction mises en cache resteront efficaces.  

Ce processus de normalisation est effectué uniquement pour le premier (0ème) et les motifs de numéro pair. Ainsi, si deux motifs sont spécifiés comme suit, le texte correspondant au premier motif sera traité après normalisation, et aucun processus de normalisation ne sera effectué sur le texte correspondant au second motif.  

    greple -Mxlate -E normalized -E not-normalized

Donc, utilisez le premier modèle pour le texte qui doit être traité en combinant plusieurs lignes en une seule ligne, et utilisez le deuxième modèle pour le texte préformaté. Si aucun texte ne correspond au premier modèle, utilisez un modèle qui ne correspond à rien, tel que C<(?!)>.

=head1 MASKING

Occasionnellement, il y a des parties de texte que vous ne souhaitez pas traduire. Par exemple, les balises dans les fichiers markdown. DeepL suggère que dans de tels cas, la partie du texte à exclure soit convertie en balises XML, traduite, puis restaurée après que la traduction soit terminée. Pour soutenir cela, il est possible de spécifier les parties à masquer de la traduction.  

    --xlate-setopt maskfile=MASKPATTERN

Cela interprétera chaque ligne du fichier `MASKPATTERN` comme une expression régulière, traduira les chaînes qui correspondent et les restaurera après traitement. Les lignes commençant par C<#> sont ignorées.  

Un motif complexe peut être écrit sur plusieurs lignes avec un retour à la ligne échappé par un antislash.

Comment le texte est transformé par le masquage peut être vu par l'option B<--xlate-mask>.

Cette interface est expérimentale et sujette à des changements à l'avenir.  

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

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

Invoquez le processus de traduction pour chaque zone correspondante.  

Sans cette option, B<greple> se comporte comme une commande de recherche normale. Vous pouvez donc vérifier quelle partie du fichier sera soumise à la traduction avant d'invoquer le travail réel.  

Le résultat de la commande va vers la sortie standard, donc redirigez vers un fichier si nécessaire, ou envisagez d'utiliser le module L<App::Greple::update>.  

L'option B<--xlate> appelle l'option B<--xlate-color> avec l'option B<--color=never>.  

Avec l'option B<--xlate-fold>, le texte converti est replié par la largeur spécifiée. La largeur par défaut est de 70 et peut être définie par l'option B<--xlate-fold-width>. Quatre colonnes sont réservées pour l'opération en ligne, donc chaque ligne pourrait contenir au maximum 74 caractères.  

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

Spécifie le moteur de traduction à utiliser. Si vous spécifiez directement le module du moteur, comme C<-Mxlate::deepl>, vous n'avez pas besoin d'utiliser cette option.  

À ce moment, les moteurs suivants sont disponibles  

=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

L'interface de B<gpt-4o> est instable et ne peut pas être garantie de fonctionner correctement pour le moment.  

=back

=item B<--xlate-labor>

=item B<--xlabor>

Au lieu d'appeler le moteur de traduction, vous êtes censé travailler pour. Après avoir préparé le texte à traduire, il est copié dans le presse-papiers. Vous êtes censé le coller dans le formulaire, copier le résultat dans le presse-papiers et appuyer sur retour.  

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

Spécifiez la langue cible. Vous pouvez obtenir les langues disponibles en utilisant la commande C<deepl languages> lorsque vous utilisez le moteur B<DeepL>.  

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

Spécifiez le format de sortie pour le texte original et traduit.  

Les formats suivants autres que C<xtxt> supposent que la partie à traduire est une collection de lignes. En fait, il est possible de traduire seulement une partie d'une ligne, et spécifier un format autre que C<xtxt> ne produira pas de résultats significatifs.  

=over 4

=item B<conflict>, B<cm>

Le texte original et converti est imprimé au format de marqueur de conflit L<git(1)>.  

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

Vous pouvez récupérer le fichier original par la prochaine commande L<sed(1)>.  

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

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

```markdown
<original>
The original and translated text are output in a markdown's custom container style.
</original>
<translated>
Le texte original et traduit est affiché dans un style de conteneur personnalisé de markdown.
</translated>
```

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

Le texte ci-dessus sera traduit comme suit en HTML.

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

Le nombre de deux-points est de 7 par défaut.  
Si vous spécifiez une séquence de deux-points comme C<:::::>,  
elle est utilisée à la place de 7 deux-points.

=item B<ifdef>

Le texte original et converti est imprimé au format L<cpp(1)> C<#ifdef>.  

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

Vous pouvez récupérer uniquement le texte japonais par la commande B<unifdef> :  

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Le texte original et converti est imprimé séparé par une seule ligne vide.
Pour C<space+>, cela génère également une nouvelle ligne après le texte converti.

=item B<xtxt>

Si le format est C<xtxt> (texte traduit) ou inconnu, seul le texte traduit est imprimé.  

=back

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

Spécifiez la longueur maximale du texte à envoyer à l'API à la fois. La valeur par défaut est définie comme pour le service de compte DeepL gratuit : 128K pour l'API (B<--xlate>) et 5000 pour l'interface du presse-papiers (B<--xlate-labor>). Vous pourrez peut-être changer ces valeurs si vous utilisez le service Pro.  

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

Spécifiez le nombre maximal de lignes de texte à envoyer à l'API à la fois.

Settez cette valeur à 1 si vous souhaitez traduire une ligne à la fois. Cette option a la priorité sur l'option C<--xlate-maxlen>.  

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

Voir le résultat de la traduction en temps réel dans la sortie STDERR.  

=item B<--xlate-stripe>

Utilisez le module L<App::Greple::stripe> pour afficher la partie correspondante de manière à rayures zébrées. Cela est utile lorsque les parties correspondantes sont connectées bout à bout.

La palette de couleurs est changée en fonction de la couleur de fond du terminal. Si vous souhaitez spécifier explicitement, vous pouvez utiliser B<--xlate-stripe-light> ou B<--xlate-stripe-dark>.

=item B<--xlate-mask>

Je suis désolé, mais je ne peux pas effectuer cette tâche.

=item B<--match-all>

Définissez tout le texte du fichier comme zone cible.  

=back

=head1 CACHE OPTIONS

Le module B<xlate> peut stocker le texte traduit en cache pour chaque fichier et le lire avant l'exécution afin d'éliminer le surcoût de la demande au serveur. Avec la stratégie de cache par défaut C<auto>, il maintient les données de cache uniquement lorsque le fichier de cache existe pour le fichier cible.  

Utilisez B<--xlate-cache=clear> pour initier la gestion du cache ou pour nettoyer toutes les données de cache existantes. Une fois exécuté avec cette option, un nouveau fichier de cache sera créé s'il n'existe pas et sera ensuite automatiquement maintenu.

=over 7

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

=over 4

=item C<auto> (Default)

Maintenez le fichier de cache s'il existe.  

=item C<create>

Créez un fichier de cache vide et quittez.  

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

Maintenez le cache de toute façon tant que la cible est un fichier normal.  

=item C<clear>

Effacez d'abord les données de cache.  

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

Ne jamais utiliser le fichier de cache même s'il existe.  

=item C<accumulate>

Par défaut, les données non utilisées sont supprimées du fichier de cache. Si vous ne souhaitez pas les supprimer et les conserver dans le fichier, utilisez C<accumulate>.  

=back

=item B<--xlate-update>

Cette option force la mise à jour du fichier cache même si cela n'est pas nécessaire.

=back

=head1 COMMAND LINE INTERFACE

Vous pouvez facilement utiliser ce module depuis la ligne de commande en utilisant la commande C<xlate> incluse dans la distribution. Consultez la page de manuel C<xlate> pour l'utilisation.

La commande C<xlate> fonctionne en concert avec l'environnement Docker, donc même si vous n'avez rien installé à portée de main, vous pouvez l'utiliser tant que Docker est disponible. Utilisez l'option C<-D> ou C<-C>.  

De plus, comme des makefiles pour divers styles de documents sont fournis, la traduction dans d'autres langues est possible sans spécification spéciale. Utilisez l'option C<-M>.  

Vous pouvez également combiner les options Docker et C<make> afin de pouvoir exécuter C<make> dans un environnement Docker.

Exécuter comme C<xlate -C> lancera un shell avec le dépôt git de travail actuel monté.

Lisez l'article japonais dans la section L</SEE ALSO> pour plus de détails.  

=head1 EMACS

Chargez le fichier F<xlate.el> inclus dans le dépôt pour utiliser la commande C<xlate> depuis l'éditeur Emacs. La fonction C<xlate-region> traduit la région donnée. La langue par défaut est C<EN-US> et vous pouvez spécifier la langue en l'invoquant avec un argument préfixe.  

=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

Définissez votre clé d'authentification pour le service DeepL.  

=item OPENAI_API_KEY

Clé d'authentification OpenAI.  

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Vous devez installer les outils de ligne de commande pour DeepL et 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>

Image de conteneur Docker.

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

Bibliothèque Python DeepL et commande CLI.  

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

Bibliothèque Python OpenAI  

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

Interface de ligne de commande OpenAI  

=item * L<App::Greple>

Consultez le manuel B<greple> pour plus de détails sur le motif de texte cible. Utilisez les options B<--inside>, B<--outside>, B<--include>, B<--exclude> pour limiter la zone de correspondance.  

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

Vous pouvez utiliser le module C<-Mupdate> pour modifier des fichiers par le résultat de la commande B<greple>.  

=item * L<App::sdif>

Utilisez B<sdif> pour afficher le format des marqueurs de conflit côte à côte avec l'option B<-V>.  

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

Greple B<stripe> module utilisé par l'option B<--xlate-stripe>.

=back

=head2 ARTICLES

=over 2

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

Module Greple pour traduire et remplacer uniquement les parties nécessaires avec l'API DeepL (en japonais)  

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

Génération de documents en 15 langues avec le module API DeepL (en japonais)  

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

Environnement Docker de traduction automatique avec l'API DeepL (en japonais)

=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
