=encoding utf-8

=head1 NAME

App::Greple::xlate - módulo de soporte de traducción para 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

El módulo B<Greple> B<xlate> encuentra bloques de texto deseados y los reemplaza por el texto traducido. Actualmente, los módulos DeepL (F<deepl.pm>) y ChatGPT (F<gpt3.pm>) están implementados como motores de backend. También se incluye soporte experimental para gpt-4 y gpt-4o.

Si quieres traducir bloques de texto normales en un documento escrito en el estilo pod de Perl, utiliza el comando B<greple> con los módulos C<xlate::deepl> y C<perl> de la siguiente manera:

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

En este comando, el patrón de cadena C<^([\w\pP].*\n)+> significa líneas consecutivas que comienzan con una letra alfanumérica y de puntuación. Este comando muestra el área a ser traducida resaltada. La opción B<--all> se utiliza para producir todo el texto.

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

Luego agregue la opción C<--xlate> para traducir el área seleccionada. Luego, encontrará las secciones deseadas y las reemplazará por la salida del comando B<deepl>.

Por defecto, el texto original y traducido se imprime en el formato de "marcador de conflicto" compatible con L<git(1)>. Utilizando el formato C<ifdef>, puedes obtener la parte deseada fácilmente con el comando L<unifdef(1)>. El formato de salida se puede especificar con la opción 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 deseas traducir todo el texto, utiliza la opción B<--match-all>. Esto es un atajo para especificar el patrón C<(?s).+> que coincide con todo el texto.

El formato de datos de marcador de conflicto se puede ver en estilo lado a lado con el comando C<sdif> con la opción C<-V>. Dado que no tiene sentido comparar en base a cada cadena, se recomienda la opción C<--no-cdif>. Si no necesita colorear el texto, especifique C<--no-textcolor> (o 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

El procesamiento se realiza en unidades especificadas, pero en el caso de una secuencia de múltiples líneas de texto no vacías, se convierten juntas en una sola línea. Esta operación se realiza de la siguiente manera:

=over 2

=item *

Eliminar los espacios en blanco al principio y al final de cada línea.

=item *

Si una línea termina con un carácter de puntuación de ancho completo, concaténala con la siguiente línea.

=item *

Si una línea termina con un carácter de ancho completo y la siguiente línea comienza con un carácter de ancho completo, concatenar las líneas.

=item *

Si el final o el principio de una línea no es un carácter de ancho completo, concatenarlos insertando un carácter de espacio.

=back

Los datos en caché se gestionan en base al texto normalizado, por lo que incluso si se realizan modificaciones que no afectan los resultados de normalización, los datos de traducción en caché seguirán siendo efectivos.

Este proceso de normalización se realiza solo para el primer (0º) y el patrón de número par. Por lo tanto, si se especifican dos patrones de la siguiente manera, el texto que coincide con el primer patrón se procesará después de la normalización, y no se realizará ningún proceso de normalización en el texto que coincida con el segundo patrón.

    greple -Mxlate -E normalized -E not-normalized

Por lo tanto, utiliza el primer patrón para el texto que se va a procesar combinando varias líneas en una sola línea, y utiliza el segundo patrón para el texto preformateado. Si no hay texto que coincida con el primer patrón, utiliza un patrón que no coincida con nada, como C<(?!)>.

=head1 MASKING

Ocasionalmente, hay partes de texto que no deseas traducir. Por ejemplo, etiquetas en archivos markdown. DeepL sugiere que en tales casos, la parte del texto a excluir se convierta en etiquetas XML, se traduzca y luego se restaure después de que la traducción esté completa. Para admitir esto, es posible especificar las partes a enmascarar en la traducción.

    --xlate-setopt maskfile=MASKPATTERN

Esto interpretará cada línea del archivo `MASKPATTERN` como una expresión regular, traducirá las cadenas que coincidan con ella y las revertirá después del procesamiento. Las líneas que comienzan con C<#> son ignoradas.

Un patrón complejo puede ser escrito en múltiples líneas con una barra invertida para escapar el salto de línea.

Cómo se transforma el texto mediante el enmascaramiento se puede ver con la opción B<--xlate-mask>.

Esta interfaz es experimental y está sujeta a cambios en el futuro.

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

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

Invoque el proceso de traducción para cada área coincidente.

Sin esta opción, B<greple> se comporta como un comando de búsqueda normal. Por lo tanto, puede verificar qué parte del archivo será objeto de la traducción antes de invocar el trabajo real.

El resultado del comando se envía a la salida estándar, así que rediríjalo a un archivo si es necesario, o considere usar el módulo L<App::Greple::update>.

La opción B<--xlate> llama a la opción B<--xlate-color> con la opción B<--color=never>.

Con la opción B<--xlate-fold>, el texto convertido se pliega según el ancho especificado. El ancho predeterminado es 70 y se puede establecer mediante la opción B<--xlate-fold-width>. Cuatro columnas están reservadas para la operación de ejecución, por lo que cada línea puede contener como máximo 74 caracteres.

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

Especifica el motor de traducción que se utilizará. Si especificas directamente el módulo del motor, como C<-Mxlate::deepl>, no necesitas usar esta opción.

En este momento, están disponibles los siguientes motores:

=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

La interfaz de B<gpt-4o> es inestable y no se puede garantizar que funcione correctamente en este momento.

=back

=item B<--xlate-labor>

=item B<--xlabor>

En lugar de llamar al motor de traducción, se espera que trabajes tú. Después de preparar el texto para ser traducido, se copian al portapapeles. Se espera que los pegues en el formulario, copies el resultado al portapapeles y presiones Enter.

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

Especifique el idioma de destino. Puede obtener los idiomas disponibles mediante el comando C<deepl languages> cuando se utiliza el motor B<DeepL>.

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

Especifique el formato de salida para el texto original y traducido.

Los siguientes formatos distintos a C<xtxt> asumen que la parte a traducir es una colección de líneas. De hecho, es posible traducir solo una parte de una línea, y especificar un formato distinto a C<xtxt> no producirá resultados significativos.

=over 4

=item B<conflict>, B<cm>

Original and converted text are printed in L<git(1)> conflict marker format.

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

Puede recuperar el archivo original con el siguiente comando L<sed(1)>.

    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 #ccc; padding: 10px; margin-bottom: 10px;">

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

El número de dos puntos es 7 por defecto. Si especificas una secuencia de dos puntos como C<:::::>, se utiliza en lugar de 7 dos puntos.

=item B<ifdef>

<<<<<<< HEAD

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

Puede recuperar solo el texto en japonés con el comando B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Original text:

=item B<xtxt>

Si el formato es C<xtxt> (texto traducido) o desconocido, solo se imprime el texto traducido.

=back

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

Especifique la longitud máxima del texto a enviar a la API de DeepL. El valor predeterminado es el establecido para la cuenta gratuita de DeepL: 128K para la API (B<--xlate>) y 5000 para la interfaz del portapapeles (B<--xlate-labor>). Es posible que pueda cambiar estos valores si está utilizando el servicio Pro.

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

Especifica el máximo de líneas de texto a enviar a la API a la vez.

Establece este valor en 1 si deseas traducir una línea a la vez. Esta opción tiene prioridad sobre la opción C<--xlate-maxlen>.

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

Vea el resultado de la traducción en tiempo real en la salida STDERR.

=item B<--xlate-stripe>

Utiliza el módulo L<App::Greple::stripe> para mostrar la parte coincidente de manera rayada en estilo cebra. Esto es útil cuando las partes coincidentes están conectadas una tras otra.

La paleta de colores se cambia según el color de fondo del terminal. Si deseas especificar explícitamente, puedes usar B<--xlate-stripe-light> o B<--xlate-stripe-dark>.

=item B<--xlate-mask>

Realice la función de enmascaramiento y muestre el texto convertido tal cual, sin restauración.

=item B<--match-all>

Establezca todo el texto del archivo como un área objetivo.

=back

=head1 CACHE OPTIONS

El módulo B<xlate> puede almacenar el texto traducido en caché para cada archivo y leerlo antes de la ejecución para eliminar la sobrecarga de preguntar al servidor. Con la estrategia de caché predeterminada C<auto>, mantiene los datos en caché solo cuando el archivo de caché existe para el archivo objetivo.

Utilice B<--xlate-cache=clear> para iniciar la gestión de la caché o limpiar todos los datos de caché existentes. Una vez ejecutado con esta opción, se creará un nuevo archivo de caché si no existe y luego se mantendrá automáticamente.

=over 7

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

=over 4

=item C<auto> (Default)

Mantenga el archivo de caché si existe.

=item C<create>

Cree un archivo de caché vacío y salga.

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

Mantenga la caché de todos modos siempre que el objetivo sea un archivo normal.

=item C<clear>

Borre primero los datos de la caché.

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

Nunca use el archivo de caché incluso si existe.

=item C<accumulate>

Por defecto, los datos no utilizados se eliminan del archivo de caché. Si no desea eliminarlos y mantenerlos en el archivo, use C<accumulate>.

=back

=item B<--xlate-update>

Esta opción fuerza la actualización del archivo de caché incluso si no es necesario.

=back

=head1 COMMAND LINE INTERFACE

Puedes usar fácilmente este módulo desde la línea de comandos utilizando el comando C<xlate> incluido en la distribución. Consulta la página del manual C<xlate> para ver cómo se utiliza.

El comando C<xlate> funciona en conjunto con el entorno Docker, por lo que incluso si no tienes nada instalado, puedes usarlo siempre que Docker esté disponible. Utiliza la opción C<-D> o C<-C>.

Además, dado que se proporcionan makefiles para varios estilos de documentos, es posible realizar traducciones a otros idiomas sin especificaciones especiales. Utiliza la opción C<-M>.

También puedes combinar las opciones de Docker y C<make> para poder ejecutar C<make> en un entorno Docker.

Ejecutar como C<xlate -C> lanzará una terminal con el repositorio git de trabajo actual montado.

Lea el artículo en japonés en la sección "VER TAMBIÉN" para más detalles.

=head1 EMACS

Carga el archivo F<xlate.el> incluido en el repositorio para usar el comando C<xlate> desde el editor Emacs. La función C<xlate-region> traduce la región dada. El idioma predeterminado es C<EN-US> y puedes especificar el idioma invocándolo con un argumento de prefijo.

=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

Configura tu clave de autenticación para el servicio DeepL.

=item OPENAI_API_KEY

Clave de autenticación de OpenAI.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Debes instalar las herramientas de línea de comandos para DeepL y 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>

Imagen del contenedor de Docker.

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

Biblioteca de Python y comando CLI de DeepL.

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

Biblioteca de Python de OpenAI

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

Interfaz de línea de comandos de OpenAI

=item * L<App::Greple>

Consulta el manual de B<greple> para obtener detalles sobre el patrón de texto objetivo. Utiliza las opciones B<--inside>, B<--outside>, B<--include> y B<--exclude> para limitar el área de coincidencia.

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

Puedes usar el módulo C<-Mupdate> para modificar archivos según el resultado del comando B<greple>.

=item * L<App::sdif>

Utiliza B<sdif> para mostrar el formato de marcador de conflicto junto con la opción B<-V>.

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

El módulo Greple B<stripe> se utiliza con la opción B<--xlate-stripe>.

=back

=head2 ARTICLES

=over 2

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

Módulo Greple para traducir y reemplazar solo las partes necesarias con la API de DeepL (en japonés)

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

Generando documentos en 15 idiomas con el módulo de API de DeepL (en japonés)

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

Entorno Docker de traducción automática con la API de DeepL (en japonés)

=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
