=encoding utf-8

=head1 NAME

App::Greple::xlate - módulo 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.35

=head1 DESCRIPTION

El módulo B<Greple> B<xlate> encuentra los bloques de texto deseados y los sustituye por el texto traducido. Actualmente se implementan los módulos DeepL (F<deepl.pm>) y ChatGPT (F<gpt3.pm>) como motor back-end. También se incluye soporte experimental para gpt-4 y gpt-4o.

Si desea traducir bloques de texto normal en un documento escrito en el estilo vaina de Perl, utilice el comando B<greple> con el módulo C<xlate::deepl> y C<perl> de la siguiente manera:

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

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

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

A continuación, añada la opción C<--xlate> para traducir el área seleccionada. Entonces, 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 "marcador de conflicto" compatible con L<git(1)>. Usando el formato C<ifdef>, puede obtener la parte deseada mediante el comando L<unifdef(1)> fácilmente. El formato de salida puede especificarse mediante 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 desea traducir todo el texto, utilice la opción B<--match-all>. Es un atajo para especificar el patrón C<(?s).+> que coincide con todo el texto.

Los datos en formato de marcador de conflicto pueden visualizarse en estilo lado a lado mediante el comando C<sdif> con la opción C<-V>. Dado que no tiene sentido comparar por 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 varias líneas de texto no vacías, se convierten juntas en una sola línea. Esta operación se realiza del siguiente modo:

=over 2

=item *

Se eliminan 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énela con la línea siguiente.

=item *

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

=item *

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

=back

Los datos de la caché se gestionan en función del texto normalizado, por lo que aunque se realicen modificaciones que no afecten a los resultados de la normalización, los datos de traducción almacenados en la caché seguirán siendo efectivos.

Este proceso de normalización sólo se realiza para el primer patrón (0) y los patrones pares. Por lo tanto, si se especifican dos patrones como los siguientes, el texto que coincida 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, utilice el primer patrón para el texto que deba procesarse combinando varias líneas en una sola, y utilice el segundo patrón para el texto preformateado. Si no hay texto que coincida con el primer patrón, entonces un patrón que no coincida con nada, como C<(?!)>.

=head1 MASKING

En ocasiones, hay partes del texto que no desea traducir. Por ejemplo, las etiquetas de los archivos markdown. DeepL sugiere que, en tales casos, la parte del texto que debe excluirse se convierta en etiquetas XML, se traduzca y, una vez finalizada la traducción, se restaure. Para ello, es posible especificar las partes que no deben traducirse.

    --xlate-setopt maskfile=MASKPATTERN

Esto interpretará cada línea del fichero `MASKPATTERN` como una expresión regular, traducirá las cadenas que coincidan con ella, y revertirá tras el proceso. Las líneas que empiezan por C<#> se ignoran.

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)

Invoca 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 comprobar qué parte del archivo será objeto de la traducción antes de invocar el trabajo real.

El resultado del comando va a la salida estándar, así que rediríjalo al 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=nunca>.

Con la opción B<--xlate-fold>, el texto convertido se dobla por el ancho especificado. La anchura por defecto es 70 y puede ajustarse con la opción B<--xlate-fold-width>. Se reservan cuatro columnas para la operación de repliegue, por lo que cada línea puede contener 74 caracteres como máximo.

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

Especifica el motor de traducción que se utilizará. Si especifica el módulo del motor directamente, como C<-Mxlate::deepl>, no necesita utilizar 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 por el momento.

=back

=item B<--xlate-labor>

=item B<--xlabor>

En lugar de llamar al motor de traducción, se espera que trabajen para. Después de preparar el texto a traducir, se copia en el portapapeles. Se espera que los pegue en el formulario, copie el resultado en el portapapeles y pulse Retorno.

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

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

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

Especifique el formato de salida del texto original y traducido.

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

=over 4

=item B<conflict>, B<cm>

El texto original y el convertido se imprimen en formato de marcador de conflicto L<git(1)>.

    <<<<<<< 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<ifdef>

El texto original y el convertido se imprimen en formato L<cpp(1)> C<#ifdef>.

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

Puede recuperar sólo el texto japonés mediante el comando B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

El texto original y el convertido se imprimen separados por una sola línea en blanco. Para C<espacio+>, también se imprime una nueva línea después del texto convertido.

=item B<xtxt>

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

=back

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

Especifique la longitud máxima del texto que se enviará a la API de una sola vez. El valor predeterminado es el mismo que para el servicio gratuito de cuenta DeepL: 128K para la API (B<--xlate>) y 5000 para la interfaz del portapapeles (B<--xlate-labor>). Puede cambiar estos valores si utiliza el servicio Pro.

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

Especifique el número máximo de líneas de texto que se enviarán a la API de una sola vez.

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

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

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

=item B<--match-all>

Establece todo el texto del fichero como área de destino.

=back

=head1 CACHE OPTIONS

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

=over 7

=item --cache-clear

La opción B<--cache-clear> puede utilizarse para iniciar la gestión de la caché o para refrescar todos los datos de caché existentes. Una vez ejecutada esta opción, se creará un nuevo archivo de caché si no existe y se mantendrá automáticamente después.

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

=over 4

=item C<auto> (Default)

Mantener el archivo de caché si existe.

=item C<create>

Crear un archivo de caché vacío y salir.

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

Mantener caché de todos modos hasta que el destino sea un archivo normal.

=item C<clear>

Borrar primero los datos de la caché.

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

No utilizar nunca el archivo de caché aunque exista.

=item C<accumulate>

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

=back

=back

=head1 COMMAND LINE INTERFACE

Puede utilizar fácilmente este módulo desde la línea de comandos utilizando el comando C<xlate> incluido en la distribución. Consulte la información de ayuda de C<xlate> para su uso.

El comando C<xlate> funciona conjuntamente con el entorno Docker, por lo que incluso si no tiene nada instalado a mano, puede utilizarlo siempre que Docker esté disponible. Utilice la opción C<-D> o C<-C>.

Además, como se proporcionan makefiles para varios estilos de documento, la traducción a otros idiomas es posible sin especificación especial. Utilice la opción C<-M>.

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

Ejecutando como C<xlate -GC> lanzará un shell con el repositorio git de trabajo actual montado.

Lea el artículo japonés en la sección L</SEE TAMBIÉN> para más detalles.

    xlate [ options ] -t lang file [ greple options ]
	-h   help
	-v   show version
	-d   debug
	-n   dry-run
	-a   use API
	-c   just check translation area
	-r   refresh cache
	-s   silent mode
	-e # translation engine (default "deepl")
	-p # pattern to determine translation area
	-w # wrap line by # width
	-o # output format (default "xtxt", or "cm", "ifdef")
	-f # from lang (ignored)
	-t # to lang (required, no default)
	-m # max length per API call
	-l # show library files (XLATE.mk, xlate.el)
        --   terminate option parsing
    Make options
	-M   run make
	-n   dry-run
    Docker options
	-G   mount git top-level directory
	-B   run in non-interactive (batch) mode
	-R   mount read-only
	-E * specify environment variable to be inherited
	-I * specify altanative docker image (default: tecolicom/xlate:version)
	-D * run xlate on the container with the rest parameters
	-C * run following command on the container, or run shell

    Control Files:
	*.LANG    translation languates
	*.FORMAT  translation foramt (xtxt, cm, ifdef)
	*.ENGINE  translation engine (deepl or gpt3)


=head1 EMACS

Cargue el fichero 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 por defecto es C<EN-US> y puede especificar el idioma invocándolo con el argumento prefijo.

=head1 ENVIRONMENT

=over 7

=item DEEPL_AUTH_KEY

Establezca su clave de autenticación para el servicio DeepL.

=item OPENAI_API_KEY

Clave de autenticación OpenAI.

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Debe 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>

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

=over 7

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

DeepL Librería Python y comando CLI.

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

Biblioteca OpenAI Python

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

Interfaz de línea de comandos de OpenAI

=item L<App::Greple>

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

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

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

=item L<App::sdif>

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

=back

=head2 ARTICLES

=over 2

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

Módulo Greple para traducir y sustituir sólo las partes necesarias con DeepL API (en japonés)

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

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

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

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

=back

=head1 AUTHOR

Kazumasa Utashiro

=head1 LICENSE

Copyright © 2023-2024 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut
