compudanzas

traducciones

notas sobre cómo colaborar con traducciones al wiki de compudanzas.

para cualquier duda o comentario, no dudes ponerte en contacto!

contribuciones

agradecemos las contribuciones por parte de las siguientes personas y colectivos:

Traducciones Alfanumérico

Roboe

~maleza

archivos fuente

los archivos fuente a traducir se encuentran en el directorio src/ de nuestros repositorios git.
estos repositorios son privados, por lo que será necesario contactarnos para colaborar :)

formato .gmo

los archivos están en el formato ".gmo" que es básicamente gemtext (".gmi") con un par de diferencias:

tipos de línea

existen dos nuevos tipos de línea, "+" y "&": el primero es para agregar html directamente a la salida en html, y el segundo es para agregar gemtext directamente a la salida en gemtext.

 + <p>html crudo para la versión web</p>
 & gemtext crudo para la versión gemini

por el momento, el único uso que se le da a estos tipos de línea es la creación de tablas en html, y su respectiva "traducción" a gemtext.

como ejemplo se puede consultar el archivo fuente de tutorial de uxn día 2:

tutorial_de_uxn_día_2.gmo

existen algunas de estas tablas en el uxn tutorial.

como sea, funciona suficientemente bien tener los archivos en gemtext puro, sin estos tipos de líneas extra.

una adición al formato que tiene que ver con el generador del wiki, es el uso de "wikilinks".

un archivo fuente puede tener un nombre de página entre llaves, y el generador lo convertirá automáticamente a un enlace correspondiente.

por ejemplo:

see the {roadmap} for updates that want to happen.

en html se convierte a un "inline link":

<p>
see the <a href='./roadmap.html'>roadmap</a> for updates that want to happen.
</p>

y en gemtext se convierte a un enlace colocado justo después de la línea en cuestión:

see the roadmap for updates that want to happen.
=> ./roadmap.gmi roadmap

notas importantes:

encuentra en la <[ruta de trabajo]> las actualizaciones que quieren suceder.

la ventaja de usar esta combinación de símbolos es que después pueden ser encontrados fácilmente.

también es posible agregar wikilinks como enlaces normales de gemtext, siguiendo este formato:

=> ./traducciones.gmi {traducciones}

nota que la extensión de los archivos ha de ser .gmi (y no .gmo); el generador se encargará de cambiar la extensión a html en la salida web.

idioma

la segunda línea de los archivos puede estar vacía o con un formato como el siguiente para indicar el idioma en cuestión:

lang=es en->{translation}

la primera parte indica el idioma de la página, y la segunda (opcional) indica el nombre de la página que contiene la traducción o versión en ese idioma.

construyendo el sitio

el repositorio solo contiene el directorio src/, sin sus salidas correspondientes. para obtenerlas hay que usar el generador.

clonando el repositorio

primero vale la pena clonar el repositorio, e.g.:

$ git clone https://codeberg.org/sejo/compudanzas

# ingresa al repositorio
$ cd compudanzas/

(hacer esto no es necesario si sigues los pasos del flujo de trabajo con git descritos abajo :)

generando el sitio

ya en el repositorio puedes ejecutar el generador, que requiere de la existencia de python3 (y awk, aunque ese ya es parte de unix) en el sistema:

$ ./generasitio.sh

verás cómo ahora hay un directorio gem/ y un directorio web/, ambos con sus salidas correspondientes.

prueba crear algún archivo .gmo con un nombre único, corre el generador, y corrobora su existencia en los directorios de salida.

además, si es un archivo no referido desde ningún otro archivo, en los mensajes de salida del generador verás un mensaje como:

{ruta de salida}: orphan

que implica que es un nodo al que no le llegan conexiones.

en general la idea es que no haya nodos "huérfanos", a menos que se trate de páginas que están en estado de borrador.

flujo de trabajo de "pull requests" con git

las siguientes notas están basadas en esta documentación de codeberg:

Pull requests and Git flow | Codeberg documentation

preparación

usaremos el repositorio de codeberg pues es más fácil crear una cuenta ahí:

compudanzas en codeberg

como sea, nota que las instrucciones son idénticas si utilizas una cuenta en tildegit, solo hay que reemplazar "codeberg.org" por "tildegit.org" en las instrucciones donde aparezca.

compudanzas en tildegit

primero que nada, crea tu cuenta :)

fork

con la sesión iniciada, ve al repositorio de compudanzas, y presiona el botón de "Fork" arriba a la derecha.

esto va a crear una copia del repositorio en tu cuenta:

https://codeberg.org/TU_USERNAME/compudanzas

llaves ssh

configura las llaves SSH de tu cuenta en codeberg de acuerdo a estas instrucciones:

Adding an SSH key to your account

clon local

ahora puedes clonar tu repositorio a un directorio local propio.

este directorio ha de ser diferente del que hayas clonado del repositorio original (ese clon ya lo puedes eliminar y solo trabajar con este nuevo que es el de tu cuenta :)

$ git clone git@codeberg.org:TU_USERNAME/compudanzas.git

(si le pusiste contraseña a tu llave SSH, el comando te la va a solicitar antes de descargar)

entra al directorio

entramos al directorio, y ya casi todo estará listo para colaborar!

$ cd compudanzas/

agrega el "upstream"

por último, esto que sigue es necesario para que puedas obtener las actualizaciones que sucedan en el repositorio original (llamado "upstream" en estos contextos); más adelante lo comentamos pero por el momento solo hay que configurarlo:

$ git remote add upstream git@codeberg.org:sejo/compudanzas.git

trabajo local

nueva rama

IMPORTANTE: antes de hacer cualquier modificación, hay que hacer una "rama" (branch) nueva, que en estos contextos se dice que es una "feature branch" (una rama para implementar una nueva "feature", en este caso una traducción)

$ git checkout -b traducción_de_equis_página

cambios

ahora puedes proceder a agregar y/o editar archivos .gmo dentro del directorio src/

para agregarlos al control de cambios de git, usa:

$ git add src/NOMBRE_DEL_ARCHIVO.gmo
$ git commit -m "DESCRIPCIÓN DEL CAMBIO QUE REALIZASTE"

también puedes usar lo siguiente para agregar todos los archivos que hayan tenido cambios:

$ git add .
$ git commit -m "DESCRIPCIÓN DEL CAMBIO QUE REALIZASTE"

sincronización

cuando desees guardar tus cambios en tu repositorio remoto, usa el siguiente comando:

$ git push

(si tu llave SSH tiene contraseña, el comando te la va a solicitar)

actualización

para mantener tu repositorio actualizado respecto a "upstream", por ejemplo justo antes de empezar a traducir un archivo, utiliza las siguientes instrucciones:

$ git pull --rebase upstream main
$ git pull

de cualquier forma, siempre conviene estar en comunicación con nosotres para que no suceda que estamos modificando considerablemente algún archivo en común.

pull request

comprobación previa

antes de hacer un "pull request" para incorporar tus cambios en el sitio de compudanzas, asegúrate de haber seguido los pasos anteriores, y de haber ejecutado el generador para ver si todo resultó correctamente en términos de los archivos de salida:

$ ./generasitio.sh

recuerda no hacer "wikilinks" a páginas que no existen: usa la <[notación provisional]> o crea el archivo correspondiente, con un título y al menos una breve descripción.

crea PR

en el sitio web de codeberg, entra a la dirección correspondiente a tu fork:

https://codeberg.org/TU_USERNAME/compudanzas

nota que la interfaz, debajo del título y la descripción del repositorio, tiene un botón que dice "Rama:" (o Branch), posiblemente seguido por el nombre "main", que es el nombre de nuestra rama principal.

presiona el botón y elige la rama que creaste para tu colaboración.

a continuación presiona el botón al lado que dice "Nuevo pull request"; esto te llevará a un formulario donde se te da la opción de agregar comentarios y de crear el pull request.

¡y listo! el PR ahora se mostrará en el repositorio principal (upstream) de compudanzas, y recibiremos una notificación para revisarlo e incorporarlo.

Pull Requests - compudanzas

por nuestra parte, ya que lo revisemos e incorporemos a la rama "main", generaremos el sitio localmente, lo publicaremos en los sitios web y gemini, y te lo haremos saber: ¡muchas gracias!

enlaces entrantes