KyMAN/LibreTranslatePlus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
main
LibreTranslatePlus/WMD/doc/es/project/details.w.md

35 KiB
Raw Permalink Blame History

[[post_data { "author" : "KyMAN", "since" : 20230521, "version" : 20230522 }]]

Detalles

El proyecto LibreTranslatePlus viene siendo una pequeña ampliación del propio proyecto LibreTranslate, pero con la peculiaridad de que éste no se integra dentro del proyecto original de LibreTranslate, sino que simplemente hace consumo de éste a modo de cliente, haciendo como un servicio el cual permite ampliar las posibilidades del propio LibreTranslate mediante el API.

flowchart LR

C[Cliente]

subgraph LibreTranslatePlus

    LTP_Q[Consulta]
    LTP_R[Respuesta]

end

subgraph LibreTranslate

    LT_Q[Consulta]
    LT_R[Respuesta]

end

C --> LTP_Q
LTP_Q --> LT_Q
LT_Q -.-> LT_R
LT_R --> LTP_R
LTP_R --> C

! note NOTA: Por evolución del proyecto, el bloque "LibreTranslate" que hay en el esquema puede ser substituido por cualquier otra conexión como "GoogleTrans" o "TGWUI" (text-generator-webui). Al ser, este proyecto, originariamente pensado para trabajar con el LibreTranslate (De ahí el nombre del proyecto), éste usa por defecto la conexión "LibreTranslate", referencia a la herramienta con el mismo nombre.

La idea es hacer un paso intermedio en la consulta y respuesta del propio LibreTranslate, haciendo las alteraciones o fases necesarias para poder realizar ciertos tipos de traducciones especiales, como pueden ser las traducciones de ficheros JSON donde sólo nos interesaría traducir valores de los elementos y nunca las llaves de los mismos, así como ignorar de la traducción valores que no son de tipo String.

Otra peculiaridad del LibreTranslatePlus es que pueda, de forma automática, traducir ficheros de forma directa sobre el sistema de archivos del OS de tal forma que el autor de los ficheros sólo tenga que pensar en un idioma mientras trabaja sobre los mismos sin necesidad de traducir más tarde. Estas traducciones automáticas se realizan a partir de patrones y parámetros que determinan y especifican qué traducir y cómo traducir.

! important IMPORTANTE: Las traducciones que puedan salir del LibreTranslate no tienen porque ser fiables al 100%. La finalidad de este proyecto ampliado del LibreTranslate es hacer una automatización de traducciones que pueda ayudar al desarrollo de ficheros internacionalizados o permitir una globalización más sencilla, aunque ésta no sea 100% fiable.

Estructura

La estructura del proyecto es la siguiente:

flowchart LR

subgraph LibreTranslatePlus

    subgraph Documentation
        A[Artbook]
        H[HTML]
        P1[PHP]
        P2[Public]
        W[WMD]
    end

    subgraph Application
        J[JSON]
        Py[Python]
        T[Tools]
    end

end

La idea es tener separada la documentación de lo que es la aplicación. La aplicación viene siendo Core y se trabajaría desde terminal/comandos y será configurable desde los ficheros JSON.

! note NOTA: El proyecto, en la parte de Python, no sigue el estándar de Python a la hora de desarrollarlo por directorios como sistema de paquetería, sino que sigue un modelo dinámico de lanzamiento por Script precompilado. Ésto simula un estilo de desarrollo tipo PHP, JS a nivel de navegador, etc. Ante la poca profundidad que requiere dicho proyecto y por comodidad en el desarrollo, se decantó por este sistema. Ésto no lo hace incompatible pues se basa en la ruta absoluta del fichero "include.py". La ruta de la configuración puede ser modificada en el diccionario de entrada del objeto "ltp", el cual sigue la misma estructura de la configuración y éste prevalecerá sobre cualquier otra configuración.

La documentación será en WMarkDown por la sencillez y versatilidad del mismo.

La estructura en sí de la aplicación Python será la siguiente:

flowchart TD

model[Modelo]
connection[Conexión]
files[Archivos]
files_translated["Archivos traducidos"]
changes{"¿Tienen cambios?"}
wait([Espera])

model -- check --> files
files --> changes
changes -- yes --> connection
connection --> files_translated
files_translated --> wait
changes -- no --> wait
wait -.-> model

El proyecto LibreTranslatePlus hace todo el trabajo a excepción de la conexión, que es la que determina la traducción, pero lo que es el propio modelo de traducción del LibreTranslatePlus es el encargado de detectar cambios así como estructurar las traducciones según el propio modelo, incluyendo la codificación o cambios necesarios para llevar la traducción customizada a cabo. Básicamente vemos que la herramienta da barridos en busca de cambios en los ficheros con esperas de X tiempo según configuración.

! important IMPORTANTE: Los modelos se orientaron a trabajo directo con los ficheros, pero éstos se realizan dentro del propio modelo, pudiendo usar este sistema con otros fines que no sea ficheros, simplemente requiere de añadirse un archivo modelo que haga dicha tarea.

! note NOTA: Las acciones customizadas cara los ficheros se desarrollan dentro de los modelos. Si ningún modelo se adapta a las necesidades, ha de crearse un nuevo modelo siguiendo las instrucciones de desarrollo del mismo que se verán más adelante.

Ejecución

La ejecución de la aplicación se basa en lo existente dentro del directorio "Tools", en la raíz de la aplicación. Dentro nos encontraremos unos ficheros los cuales atacan a los ficheros de ejecución de la aplicación dentro de Python. Dichos ficheros los hay tanto en versión DOS en BAT (Batch) como en versión UNIX en SH (Bash), y éstos, sin contar con la extensión, serían los siguientes:

  • ignore LibreTranslatePlus: Ejecuta el archivo "run.py" el cual está destinado a arrancar un demonio de la aplicación.
  • ignore LibreTranslatePlus.test: Ejecuta el archivo "test.py" y ha de venir acompañado por el nombre de la prueba, sin extensión, que halla dentro del directorio "Tests" en la raíz del proyecto. Si el fichero de testeo no existe, éste finalizará automáticamente con un mensaje conforme no se encontró el test.

Ejemplos de ambas ejecuciones pueden ser los siguientes:

#/bin/bash
./LibreTranslatePlus.test.sh com
./LibreTranslatePlus.test.sh com2
./LibreTranslatePlus.sh

A un nivel más profundo, la ejecución "run.py" empieza con una verificación de carga de los ficheros dados en el "include.py" donde han de estar todos "OK", en caso contrario, algún fichero tiene mal el Path o directamente, no existe, y ésto puede afectar al funcionamiento del programa. Una vez cargados los ficheros, éste construirá el objeto "ltp", de la sigla de "LibreTranslatePlus", y como tal, también sus subobjetos necesarios para funcionar, los cuales, en su orden, son:

  1. ignore Settings: Configuración.
  2. ignore I18N: Internacionalización. Gestión de textos e idiomas.
  3. ignore Threads: Gestión de hilos de proceso.
  4. ignore Terminal: Terminal de comandos para permitir interactuar a los usuarios con la aplicación en Core.
  5. ignore Connections: Gestión de conexiones con los distintos Drivers accesibles.
  6. ignore Models: Gestión de modelos de traducción.

Tras la creación de los objetos, éste iniciará de forma automática, si así está establecido en la configuración, la iniciación de los mismos con la carga de datos (Archivos de configuración, I18N, etc.) y la creación de las conexiones y modelos. Una vez esté todo creado, éste ejecutará los modelos de forma autónoma si así está en la configuración.

! note NOTA: Por defecto, en la configuración está por defecto que se autoinicie tanto el objeto "ltp" como los modelos.

Configuración

La configuración se establece en JSON y por defecto, habrá un archivo de configuración el cual sería "/JSON/LibreTranslatePlus.py.settings.json" el cual, no se aconseja alterar, aunque sí tiene todos los parámetros existentes para la aplicación; y por otro lado, podemos crear un archivo alternativo de configuración con el Path "/JSON/LibreTranslatePlus.py.settins.secrets.json" el cual es ignorado por el Git desde el ".gitignore" el cual puede sobreescribir cualquiera de los valores dados en el fichero de configuración por defecto, teniendo preferencia sobre él, y será ahí donde se configuren los modelos y las conexiones.

! note NOTA: En este apartado hablaremos únicamente de la configuración general, lo que viene siendo la configuración de cada conexión o modelo se hablará de ello en su apartado correspondiente.

Para empezar, vemos que el fichero de configuración por defecto se divide por bloques según a lo que hace referencia cada uno de los parámetros de configuración; y para continuar, vemos que tenemos una serie de parámetros de configuración Booleanos donde en el nombre termina en "_message" los cuales determinan si se muestran o no los mensajes a los que hacen referencia. Sabiendo ésto, salvo los parámetros de mensajes, a continuación veremos todos los parámetros comunes de configuración en orden de bloques:

! important IMPORTANTE: Para anular un parámetro, igualarlo a "null", salvo que éste permita retorno de valores nulos.

Por otro lado, y para terminar con la configuración, existen tres parámetros globales generales acerca de los mensajes los cuales son:

  • ignore show_ok_message: Por defecto, determina que se muestran todos los mensajes de tipo OK que están condicionados.
  • ignore show_error_message: Por defecto, determina que se muestran todos los mensajes de tipo ERROR (ERRO) que están condicionados.
  • ignore show_exception_message: Por defecto, determina que se muestran todos los mensajes de tipo EXCEPCION (EXCE) que están condicionados.

! note NOTA: Estos valores de muestreo de mensajes van condicionados a que no halla otro valor que predomine sobre éste, normalmente, mensajes específicos de cada frase o texto.

Instalación

Para poder instalar este proyecto totalmente funcional en su entorno local, lo primero sería tener el repositorio de Git y Python3 en el entorno local, que cómo ejemplo de la instalación del mismo en Debian tenemos:

#!/bin/bash
sudo apt install git python3

Una vez instaladas estas dependencias, hay que clonar el proyecto en un directorio local el cual estaría al gusto o necesidades del usuario:

#!/bin/bash
git clone https://git.k3y.pw/KyMAN/LibreTranslatePlus

Una vez clonado el repositorio, tenemos que agregarle los parámetros "secretos", una serie de ficheros que no están integrados en el proyecto pues son configuraciones específicas del entorno donde se ejecuten así como de los usuarios que lo trabajen. Primero habría que ir al directorio JSON que se encuentra en la raíz del proyecto, y dentro de éste, crear el archivo "LibreTranslatePlus.py.settings.secrets.json", el cual será cargado automáticamente, sobreescribiendo la configuración inicial del proyecto que se encuentra en el archivo "LibreTranslatePlus.py.settings.json". En este fichero hay que configurar las conexiones y los modelos en base a cómo tengamos configurados los servicios, los cuales pueden ser remotos o en uso de entorno local.

! note NOTA: El uso local de los servicios requiere de la instalación del servicio, por lo que antes de configurar nada, hay que mirar la sección de cómo se instala dicho servicio. La configuración irá en base a dicho servicio.

A continuación se expone un ejemplo de configuración de servicio de traducción directa como si fuere a éste proyecto.

{
    "connections" : {
        "LibreTranslatePlus_connection" : {
            "type" : "LibreTranslate", 
            "url" : "http://127.0.0.1:5000"
        }
    }, 
    "models_files" : {
        "LibreTranslatePlus_model" : {
            "model" : "KJSON", 
            "paths" : "/home/USER/git/LibreTranslatePlus/JSON/I18N/LibreTranslatePlus.py.i18n.{key}.json", 
            "main_language" : "espanol", 
            "connection_key" : "LibreTranslatePlus_connection", 
            "protected_fragments" : [
                "'\\{file\\}\\(\\{method\\}\\)\\[\\{line\\}\\]'\\{lines\\}\\n+\\{exception_message\\}", 
                "'?(LibreTranslate(Plus)?|KJSON|translate)'?", 
                "https?\\:\\/{2}[^\\s]+"
            ]
        }
    }, 
    "connections_show_get_error_message" : false, 
    "connections_show_get_ok_message" : false, 
    "default_language" : "espanol"
}

En este ejemplo también se sobreescriben dos variables que condicionan muestreo de impresiones por la terminal y del idioma por defecto de trabajo.

Por otro lado, si lo que se desea es instalar localmente la documentación del proyecto, hace falta hacer un sitio Web para PHP, ya sea vía Nginx, Apache2, etc. Así como el proyecto WMarkDown. Y una vez instalados dichos elementos, hay que ejecutar el fichero "wmd.php" dentro del directorio "Public" que se encuentra dentro del raíz del proyecto.

! note NOTA: Está diseñado para poder ser ejecutado desde la Web para así poder actualizar mediante git con la ejecución del fichero "git_update.php" que se encuentra dentro del mismo directorio, de esta forma se evita en la medida de lo posible, el contacto directo o intrusión dentro del servidor.

https://libretranslateplus.local/wmd.php
https://libretranslateplus.local/git_update.php

La configuración de la zona Web ha de ser como el directorio "Public" es la ruta raíz del dominio, pero hay que coger todo el proyecto en la zona. Un ejemplo de configuración vía Apache2 puede ser el siguiente:

<VirtualHost *:80>
	ServerName				libretranslateplus.local
	DocumentRoot			/home/USER/git/LibreTranslatePlus/Public
    RewriteEngine           On
    RewriteCond             %{HTTPS}  !=on
    RewriteRule             ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
	ErrorLog				${APACHE_LOG_DIR}/error_ltp_80.log
	CustomLog				${APACHE_LOG_DIR}/access_ltp_80.log combined
</VirtualHost>

<VirtualHost *:443>
	ServerName				libretranslateplus.local
	DocumentRoot			/home/USER/git/LibreTranslatePlus/Public
	<Directory /home/USER/git/LibreTranslatePlus>
		Options			    +Indexes +FollowSymLinks +MultiViews
		DirectoryIndex		index.html index.php
		AllowOverride	    all
		Order			    Allow,Deny
		Allow			    from all
		Require			    all granted
	</Directory>
    SSLEngine               on
    SSLCertificateFile      /home/USER/Certificates/Autosigned/certificate.ltp.local.crt
    SSLCertificateKeyFile   /home/USER/Certificates/Autosigned/key.ltp.local.key
	ErrorLog				${APACHE_LOG_DIR}/error_ltp_443.log
	CustomLog				${APACHE_LOG_DIR}/access_ltp_443.log combined
</VirtualHost>

! note NOTA: La documentación no requiere de estar en un entorno SSL, sin embargo, por seguridad, aunque sea dentro del área local, se aconseja dicha configuración.

Para poder configurar todo el entorno hacen falta instalar los siguientes repositorios:

#!/bin/bash
sudo apt install apache2 php8.1
cd PATH_WMARKDOWN
git clone https://git.k3y.pw/Whalers/WMarkDown

! note NOTA: El Path del WMarkDown puede ser cualquier sitio del entorno local, sin embargo, si no se quiere configurar fuera de lo que aquí establecido, se aconseja que esté al mismo nivel donde se encuentra el LibreTranslatePlus, quedando ambos en el mismo directorio.

! note NOTA: La versión de PHP ha de ser 7.0 o superior. En la mayoría de casos debería de funcionar sin problemas en la versión 5.6 en adelante. No tiene incompatibilidades conocidas en la versiones más recientes de PHP.

! note NOTA: Para el uso que se le va a dar en el entorno local, el WMarkDown no requiere de configurarse una zona específica para sí mismo. Sin embargo, sí requiere de configurar el archivo "WMarkDown.Secrets.php", el cual estaría dentro del directorio PHP dentro del directorio raíz del proyecto, y el cual sería el siguiente:

<?php

    namespace WMarkDown;

    class Secrets{

        const wmarkdown = [
            "root" => "/home/USER/git/WMarkDown",
            "html_base" => "/home/USER/git/WMarkDown/HTML/base.wmarkdown.html",
            "title" => "WMarkDown",
            "db_file" => "/home/USER/git/data/WMarkDown.wmd.sqlite",
            "wmd_file" => "/home/USER/git/WMarkDown/HTML/script.w.md",
            "wmd_file_empty" => "/home/USER/git/WMarkDown/HTML/file.w.md",
        ];

    };

! note NOTA: Los Paths pueden ser alterados siempre que existan o estén destinados a tener permisos y ser creados por el propio WMarkDown.

Una vez instalados, hace falta habilitar en Apache2 los módulos "ssl".

#!/bin/bash
sudo a2enmod ssl
sudo systemctl apache2 restart

El archivo "wmd.php" depende del archivo "LibreTranslatePlus.Secrets.php" el cual se encuentra en el directorio PHP dentro del directorio raíz del proyecto, el cual puede ser el siguiente:

<?php

    namespace LibreTranslatePlus;

    class Secrets{

        const wmarkdown = [
            "root" => "/home/USER/git/LibreTranslatePlus",
            "html_base" => "/home/USER/git/LibreTranslatePlus/HTML/base.ltp.html",
            "title" => "LibreTranslatePlus",
            "db_file" => "/home/USER/data/WMarkDown.wmd.sqlite",
            "wmd_file" => "/home/USER/git/WMarkDown/HTML/script.w.md",
            "wmd_file_empty" => "/home/USER/git/WMarkDown/HTML/file.w.md"
        ];

    };

Drivers

Los Drivers no son más que una librería que unifica el sistema de conexión así como los métodos cara cada una de las herramientas que hay en el proyecto.

Por defecto, los Drivers parten de la extensión de la clase "LibreTranslatePlus.Abstracts.Drivers" la cual fuerza la situación de tener los métodos:

  • ignore languages: Método sin parámetros que retorna una lista de diccionarios la cual contiene todos los idiomas que puede trabajar dicho Driver, ya sea todos los que el servidor admite o los que fueron limitados por el usuario. El diccionario tiene las siguientes entradas:
    • ignore code: Código de idioma en ISO-3166.
    • ignore name: Nombre del idioma en inglés.
    • ignore key: Llave de idioma. Parámetro customizado el cual sería el nombre del idioma en el idioma nativo y con letras latinas no especiales.
  • ignore translate: Método el cual genera una traducción de un texto en un idioma a otro. Sus parámetros son:

! note NOTA: la llave en los idiomas ("ignore key") existe por el hecho de que la normativa ISO-3166 engloba dentro del mismo código múltiples idiomas, como puede ser el caso del Gallego con el Galés o el Groenlandés (Idioma minoritario nativo de Groenlandia, siendo el principal el Danés), el cual puede aparecer como "ga" (Galés) o "gl" (Groenlandés). Por este motivo se creó el sistema de llaves de idiomas.

! note NOTA: El método "ignore translate" posee un parámetro opcional a mayores que determina el formato por idea original de LibreTranslate, que viene siendo el formato.

En caso de no estar implementados en el Driver dichos métodos, éstos alertarán con un WARN que éstos no están.

! note NOTA: La configuración del gestor de conexiones está explicada más arriba, en el apartado de conexiones.

Los Drivers se aplican desde la configuración a partir del parámetro de configuración ignore connections, el cual es un diccionario donde la llave de cada elemento es la llave que identifica a dicha conexión, y éste ha de tener como valor otro diccionario que establece los parámetros de configuración de la conexión y el parámetro ignore type que determina el nombre del Driver al que va referido para establecer el nuevo Driver.

! note NOTA: Si el nombre del Driver no existe éste imprimirá un error.

Los Drivers son los siguientes:

Driver LibreTranslate

El Driver "LibreTranslate" permite gestionar una conexión contra un servidor LibreTranslate y hacer uso de los métodos básicos de los Drivers, más uno más el cual es "query", que permite hacer una consulta directa a dicho servidor. Los parámetros de configuración son los siguientes:

El primer bloque es para la configuración global que se aplicará por defecto a todas las conexiones; y el segundo bloque es la configuración específica que se establece para cada conexión.

Modelos

Los modelos determinan la metodología o estrategia de traducción. Los modelos han de basarse en la extensión de la clase "LibreTranslatePlus.Abstracts.Models" la cual establece una gestión de hilo de procesos independiente con inicio y detención mediante métodos "start" y "stop" respectivamente los cuales inician o detienen el hilo asignado. Dicho hilo se ejecuta infinitamente mediante un "timer" el cual puede ser asignado desde el parámetro de configuración global ignore default_model_timer o el parámetro de configuración propio de cada modelo ignore timer. El método al que ataca es ignore execute y cada iteración espera tras la finalización de la ejecución en cuestión. El método "ignore execute" ha de ir con un parámetro el cual es el ID del hilo al que pertenece para poder interactuar con él desde dentro del propio método.

! note NOTA: En el código, el método "ignore execute" es llamado de forma anidada desde un método anónimo pues de forma directa no pilla completamente la iteración. Actualmente no se sabe por qué pasa esto pero no afecta al funcionamiento ni rendimiento inicial, por lo que de momento se dejará como está actualmente.

Los modelos que hay son los siguientes:

Modelo KJSON

El modelo KJSON está diseñado específicamente a la traducción de archivos de internacionalización JSON de los proyectos de KyMAN. Éste se basa en la idea de que los textos pueden contener variables, por lo que la traducción no es completa y hay que conseguir aislar a las variables de la traducción. Las variables, por lo general, representan un nombre o valor, por lo que si se les establece un conjunto de caracteres los cuales no son traducibles a ningún idioma, véase el caso de las siglas, éstos permanecerán en la traducción íntegramente, permitiendo así poder traducir y luego buscar dichas siglas otra vez a sus variables originales.

! note NOTA: Este modelo está en evolución por motivos de fallo a la hora de que todos los idiomas interpreten la misma cantidad de nombres en la misma frase, así como el orden de los mismos, pero la función inicial la consigue llevar a cabo.

Por lo tanto, la estructura de ejecución de este modelo viene siendo la siguiente:

flowchart LR

KJSON["iteración KJSON"]

subgraph Paths
    FI(["Iterador de ficheros"])
    FS["Fichero original"]
    FCS["Caché fichero original"]
end

subgraph Textos
    TI(["Iterador de textos"])
    TS["Texto original"]
    TCS["Caché texto original"]
end

subgraph Idiomas
    LI(["Iterador de idiomas"])
    LT["Texto en idioma"]
    LTC["Texto cache en idioma"]
    TE([Codificar])
    T{Traducir}
    TD([Decodificar])
end

KJSON -- load --> FI
FI -- end --> KJSON
FI -- more --> FS
FS -- check --> FCS
FCS -- "without changes" --> FI
FCS -- "with changes" --> TI
TI -- end --> FI
TI -- more --> TS
TS -- check --> TCS
TCS -- "not exists" --> LI
TCS -- changed --> LI
TCS -- "without changes" --> TI
LI -- end --> TI
LI -- more --> LT
LT -- check --> LTC
LTC -- "no changes" --> LI
LTC -- changed --> TE
TE --> T
T --> TD
TD --> LI

Este modelo tiene los siguientes parámetros de configuración:

El primer bloque representa la configuración global por defecto que se le da en la configuración general; y el segundo bloque vienen siendo los valores que se le detallan al propio modelo.

[[html_data { "title" : "Detalles - LibreTranslatePlus", "url" : "https://libretranslateplus.k3y.pw/doc/es/project/details.html", "author" : "KyMAN", "since" : 20230521, "version" : 20230522, "key_words" : "kyman,libretranslateplus,ltp,libretranslate,python,py,traductor,proyecto,detalles", "description" : "Detalles de LibreTranslatePlus.", "project" : "LibreTranslatePlus", "logo" : "https://libretranslateplus.k3y.pw/images/LibreTranslatePlus.png", "language" : "es" }]]