Open Tools and R Packages for Open Science

Mauro Lepore

Hace poco Yanina Bellini Saibene nos recordó actualizar el perfil de Slack: Después de hacer eso, decidí actualizar mis fotos de perfil en el sitio web de rOpenSci, y termine aprendiendo algunos trucos de git que voy a compartir acá.

Trucos de Git para trabajar con repositorios grandes

Yanina Bellini Saibene

Sébastien Rochette

Alejandra Bellini

Lucio Casalla

Steffi LaZerte

Este es el segundo artículo de nuestra serie de entrevistas “Conociendo a las estrellas del universo R”. Nuestro objetivo es presentar a los grupos de trabajo y a las personas que están detrás del desarrollo de software y paquetes que utilizamos y que están disponibles a través del R-Universe.

Aprender, ayudar y compartir. El método de ThinkR para crear una comunidad cada vez más grande y amigable de R

Pachá (aka Mauricio Vargas Sepúlveda)

Resumen censo2017 es un paquete en R diseñado paraorganizar los archivos Redatam

 1

proporcionados por el Instituto Nacional de Estadísticas de Chile en formatoDVD

 2

. Este paquete fue inspirado por citesdb(Noam Ross, 2020) y taxadb(Carl Boettiger et al, 2021).Esta entrada trata sobre este paquete, elproblema que resuelve, cómo usarlo, y el hecho de que el paquete y su proceso derevisión se hicieron íntegramente enespañol.

La Historia de censo2017, el Primer Paquete de rOpenSci Revisado en Español

Maëlle Salmon

Como parte de nuestro proyecto editorial multilingüe y con financiación del Consorcio R hemos trabajado en el paquete R babeldown para traducir contenido basado en Markdown utilizando la API de DeepL.En esta nota técnica, mostraremos cómo puedes utilizar babeldown para traducir un artículo de blog que utiliza Hugo.

Cómo traducir un artículo de blog de Hugo con Babeldown

¡Nos complace abrir la convocatoria para la segunda cohorte de

 Campeonas/es y Mentoras/es

para el Programa de rOpenSci 🎉 ! Este programa continuará apoyando nuestro objetivo de identificar, reconocer y recompensar a los miembros apasionados de la comunidad que ayudan a la comunidad a crecer y mejorar.

¡Convocatoria abierta para la presentación de candidaturas al Programa de Campeonas y Campeones de rOpenSci!

Karthik Ram

Estimada comunidad rOpenSci,  Este es un anuncio un poco agridulce… después de casi 13 años, es hora de que me retire como Director Ejecutivo de rOpenSci. En el verano de 2011 cofundé rOpenSci junto con un grupo de colegas dedicados. Lo que comenzó como una colaboración informal entre entusiastas de la ciencia abierta evolucionó rápidamente hacia algo mucho más significativo.

Del Director Fundador: Mi despedida de rOpenSci

Resumen   Este artículo trata sobre los usos sorprendentes que he observado y las preguntasque recibo sobre el paquete R censo2017, una herramienta paraacceder a los datos del censo chileno de 2017, que he recibido desde que fue revisado por paresa través de rOpenSci hace un año.

Usos interesantes de censo2017 un año después de su publicación

El Universo R es utilizado por profesionales de distintos ámbitos, aunque todos persiguen el mismo objetivo:

 ofrecer sus paquetes de R de manera simple y accesible

. Desde rOpenSci trabajamos para ofrecer herramientas que faciliten el acceso a datos y software de investigación generado con buenas prácticas de desarrollo de software y en una comunidad amigable.

El multiverso de rOpenSci

Juan Pablo Ruiz Nicolini

Corría el año 2015, un estudiante de maestría de Ciencia Política tenía que procesar datos para entregar su tésis y decidió aprovechar la oportunidad para aprender a usar R. Al largo y tortuoso camino del requisito académico se agregó un grado de dificultad extra: incorporar un software de programación desde cero, con una curva de aprendizaje algo empinada.

Divide y venceras: de polar al Polarverse

R es un lenguaje y un entorno para la computación estadística.Existen varias herramientas y enfoques para interactuar con R, pero no todos son accesibles con lectores de pantalla.Esta guía proporciona una visión general de las herramientas y técnicas disponibles para las personas que usan lectores de pantalla en diferentes sistemas operativos, con consejos prácticos y recursos para ayudarles a navegar por el entorno R.Puede que esta guía no esté

Recursos para utilizar R con lectores de pantalla

Twitter es una de las plataformas y redes sociales preferidas por la comunidad de R y por las comunidades de datos, ciencia abierta e investigación. Desde el comienzo de rOpenSci hemos utilizado Twitter para conectarnos con nuestra comunidad y otras comunidades similares, para compartir lo que hacemos y para formar parte de las conversaciones en torno a los temas importantes para nuestra misión.

Canales de comunicación de rOpenSci: Twitter

¿Porqué un programa de Campeones y Campeonas? Estos programas se diseñan para identificar, reconocer y premiar a miembros apasionados de nuestras comunidades. En rOpenSci, reconocemos que existe una consternadora falta de diversidad en el ecosistema de las comunidades de software de investigación y de código abierto. La Comunidad R no es una excepción;

¡Anunciamos el programa de Campeones y Campeonas de rOpenSci!

Noam Ross

Me complace, emociona y llena de humildad anunciar que asumo el cargo de Director Ejecutivo de rOpenSci a partir del 1 de Abril. En primer lugar, permítanme expresar mi gratitud a nuestro Director Ejecutivo saliente y amigo Karthik Ram por su liderazgo y tutoría al frente de rOpenSci durante la última década. Ha sido una mano firme y un visionario que ha ayudado a nuestra comunidad a lograr tanto juntos en este tiempo.

Hola de nuestro nuevo Director Ejecutivo

Elio Campitelli

Marcos Prunello

Pao Corrales

Las personas

 campeonas

de una comunidad son

 personas que asumen una mayor responsabilidad en el éxito, la sostenibilidad y/o el funcionamiento de una comunidad

.

 1

rOpenSci desarrolla un programa de campeones y campeonas enfocado y pensado para que participen personas que pertenecen a grupos histórica y sistemáticamente excluidos de las comunidades de software abierto y de software de investigación.

Participación  Latinoamérica en el Programa de Campeonas y Campeones de rOpenSci

Un nuevo artículo de nuestra serie de entrevistas “Conociendo a las estrellas del universo R”. Nuestro objetivo es presentar a los equipos y personas que están detrás del desarrollo de software y paquetes que utilizamos y que están disponibles a través del R-universe. Queremos destacar y explorar diferentes equipos y proyectos de todo el mundo, el trabajo que realizan, sus procesos y usuarios.

Conociendo a las estrellas del Universo R: El universo R contra las enfermedades.

Tal como lo anticipamos en noviembre del 2022 los cambios aplicados en Twitter han generado un espacio menos seguro y amigable para nuestra comunidad. Es por eso que a partir de

 Junio de 2023

, dejaremos de interactuar en esa plataforma. Mantendremos la cuenta con la esperanza de poder volver cuando Twitter vuelva a ser un espacio seguro y solidario, pero mientras tanto centraremos nuestros esfuerzos de comunicación en otros lugares.

Los canales de comunicación de rOpenSci para un intercambio seguro y amigable

Conociendo a las estrellas del Universo R: PEcAn, un proyecto de código abierto para cuidar el planeta

Conociendo a las estrellas del Universo R: Investigando nuestro cerebro con la magia del universo R

¡El programa de campeones arrancó con todo este 2023! Nos complace informar sobre los dos primeros meses de nuestro primer programa de campeones y campeonas. En septiembre de 2022 hicimos el lanzamiento del programa, anunciando el llamado a aplicar a personas que quisieran participar. Recibimos un total de 102 solicitudes de 31 países diferentes.

Puntapié inicial de nuestro programa de campeonas y campeones

Jeroen Ooms

Encontrar la herramienta adecuada para el trabajo   Lo más difícil de usar R con eficacia es encontrar los mejores paquetes para el problema que intentas resolver. Creo que esto es incluso, más importante que dominar el lenguaje en sí. Cosa que irás adquiriendo a medida que empieces a utilizar R con más frecuencia.

Descubrir y aprender todo lo que hay que saber sobre los paquetes de R utilizando r-universe

Esta entrada del blog pretende ayudarte a iniciarte en la comunidad rOpenSci destacando algunos links y actividades clave. Si tienes alguna pregunta, no dudes en ponerte en contacto con nuestra Community Manager, Yanina Bellini Saibene por correo electrónico o programa una reunión con ella. Estamos a tu disposición para que comiences tu camino con nuestra comunidad. ¡Te damos la bienvenida! ¿Por dónde empiezo?

Cómo participar en rOpenSci

En rOpenSci, creamos y curamos software para ayudar a quienes hacen ciencia en el ciclo de vida de los datos. Estas herramientas acceden, descargan, gestionan y archivan datos científicos de forma abierta y reproducible. Desde el principio, nos dimos cuenta de que esto sólo podía ser un esfuerzo comunitario.

Cómo rOpenSci utiliza la revisión de código para promover la ciencia reproducible

Nos agrada anunciar que, con el aporte de Chan Zuckerberg Initiative, NumFOCUS y R Consortium, estamos comenzando el proceso de traducir los materiales de rOpenSci sobre buenas prácticas de desarrollo de software, revisión de código y contribución a proyectos de código abierto al español.Como parte de este esfuerzo, también estamos desarrollando guías y herramientas para traducir recursos de código abierto y alcanzar una mayor audiencia.

Agrandando nuestra comunidad con publicaciones multi-idioma

Los procesos de revisión de software y revisión de software estadístico que realizamos en rOpenSci dependen del trabajo voluntario de quienes realizan estas tareas de revisión y edición.El equipo editorial gestiona el flujo diario de envíos, recluta personas para revisar y guía el proceso de revisión por pares de principio a fin.

Desafíos y soluciones editoriales en la revisión por pares de software

Durante useR! 2021 Jeroen Ooms presentó el proyecto universo R en su

 keynote

.Comentó sobre el proyecto, los casos de uso y repasó las instrucciones para crear tu propio

 universo-r

. En este post the explico como crear el tuyo a partir de la experiencia de crear el mio.

Creando Tu R-universe

Nos complace anunciar el nuevo Grupo de Trabajo de Documentación Multilingüe del R Consortium.Este Grupo de Trabajo surgió luego de varias conversaciones durante el R Project Sprint 2023 y supervisará la implementación del soporte de documentación multilingüe en R y organizará los esfuerzos de traducción de la comunidad.Nuestro primer proyecto es el paquete (experimental)

 rhelpi18n

que añade soporte en R para el uso de

Documentación multilingüe en paquetes de R

Las orientaciones de la Revisión por Pares de Software de rOpenSci se compilan en un libro en línea que sigue mejorando.Esta articulo de blog resume las novedades de nuestra Guía de Desarrollo 0.9.0, con todos los cambios enumerados en la sección registro de cambios.¡Ahora disponible en español!

rOpenSci Dev Guide 0.9.0: ¡Ahora multilingüe! Y mejor

Esta es la primera entrega de nuestra serie de entrevistas

 “Conociendo a las estrellas del universo R”

. Tenemos como objetivo introducir los grupos de trabajo y las personas que están detrás del desarrollo del software y paquetes que muchos utilizamos y que se encuentran disponibles en

 R-Universe

. Queremos resaltar y conocer diferentes proyectos alrededor del mundo, el trabajo que hacen, sus procesos y usuarios.

Conociendo a las estrellas del universo R: comunidad R, intercambiar y aprender

¡Hola! Soy Yanina Bellini Saibene, tu nueva Community Manager. Estoy muy entusiasmada de unirme a rOpenSci con este rol y así poder apoyar un proyecto tan importante en la ciencia abierta y en la Comunidad R.  Cuando vi la convocatoria para el puesto, pensé que mis más de 20 años de experiencia trabajando en comunidades, siendo profesora e investigadora se alineaban perfectamente.

Presentamos a la nueva Community Manager de rOpenSci, Yanina Bellini Saibene

rOpenSci - herramientas abiertas para una ciencia abierta

R es un lenguaje y un entorno para la computación estadística.Existen
varias herramientas y enfoques para interactuar con R, pero no todos son
accesibles con lectores de pantalla.Esta guía proporciona una visión
general de las herramientas y técnicas disponibles para las personas que
usan lectores de pantalla en diferentes sistemas operativos, con
consejos prácticos y recursos para ayudarles a navegar por el entorno
R.Puede que esta guía no esté completa, pero espero que sirva como un
valioso punto de partida. Agradecemos las sugerencias de otras personas
para mejorarla aún más.

## ¿Por dónde empezar?

El conjunto de herramientas y recursos de esta sección es válido para
todos los sistemas operativos.

[El proyecto R para el cálculo estadístico](https://www.r-project.org)
es el sitio donde puedes descargar R para Windows, Linux y Mac.

Al instalar R, se dispone de funciones estadísticas básicas.A esta
instalación la llamamos "R base".Se añaden funcionalidades a R base
escribiendo paquetes en el lenguaje R.El Dr. Jonathan Godfrey ha escrito
un paquete llamado BrailleR que produce resultados estadísticos en
formato de texto o Braille que son más accesibles que las funciones de R
base.[El sitio web del Dr.
Godfrey](https://r-resources.massey.ac.nz/BrailleR/) contiene
información sobre este paquete, así como consejos generales sobre el uso
de R como una persona usuaria de Braille o de lector de pantalla.

El sitio [Personas ciegas usuarias de
R](https://www.nfbnet.org/mailman/listinfo/blindrug_nfbnet.org) es otro
lugar al que puedes acudir para obtener respuestas sobre el uso de R.

## ¿Cómo interactúas con R?

Las posibilidades incluyen:

- Ejecutar R en el [símbolo del sistema en una
  terminal](https://es.wikipedia.org/wiki/Emulador_de_terminal). Esto
  tiene la gran desventaja de no guardar los comandos que usaste y la
  salida que generaron.
- Usar un editor de texto para escribir scripts (grupos de comandos R) y
  enviarlos en la [línea de
  comandos](https://es.wikipedia.org/wiki/Interfaz_de_l%C3%ADnea_de_comandos).
  Este solía ser el enfoque preferido para muchas personas ciegas, pero
  es menos conveniente que la herramienta interactiva.
- Utilizar la GUI (interfaz gráfica de usuario) de R. Esto puede ser
  accesible en Windows, pero es inaccesible en Mac.
- Utilizar un entorno de desarrollo integrado (IDE) accesible para
  escribir, editar, enviar y reutilizar código R (véase la siguiente
  sección).

### IDEs y sistemas operativos

Una IDE es un software que ayuda a los programadores a desarrollar
software de forma eficiente proporcionando un conjunto de herramientas
en el mismo entorno. Existen varios IDE en el mercado.Los IDE tienen
varias ventajas sobre el trabajo en el símbolo del sistema o en la GUI
de R:

- Comandos especializados para ejecutar el código y revisar los
  resultados.
- Ayuda con la edición haciendo cosas como notificar al usuario de
  paréntesis mal cerrados.
- Cambiar fácilmente entre la edición de código y la lectura de la
  salida.
- Facilidad para guardar el trabajo y reutilizarlo más tarde.

El popular IDE RStudio no es accesible para usuarios de lectores de
pantalla en ninguna plataforma.Es muy importante que los docentes
entiendan que sus estudiantes ciegos no tendrán acceso a este entorno y,
por tanto, no utilizarán sus botones o accesos directos. Lo mismo se
aplica a quienes escriben documentación.

#### Windows

Muchos usuarios ciegos de R utilizan el [Visual Studio Code (VS
Code)](https://code.visualstudio.com) IDE con lectores de pantalla.El
sitio [Extensión R para código
VS](https://marketplace.visualstudio.com/items?itemName=REditorSupport.r)proporciona
funciones adicionales para que trabajar en R resulte más cómodo.

Una segunda opción para trabajar con R en Windows es instalar [Windows
Subsystem for
Linux](https://learn.microsoft.com/en-us/windows/wsl/about)(WSL).Con
WSL, puede ejecutar un entorno de línea de comandos de Linux en
Windows.Puedes acceder a la Terminal utilizando los lectores de pantalla
NVDA o JAWS.Se podría acceder a una sesión de R en el terminal, o se
podría leer la entrada y la salida en el editor de texto de su elección
desde el sistema operativo Windows o Linux.Esta sería una gran opción
para las personas que son usuarios experimentados de NVDA o JAWS que
quieren aprender sobre R y Linux.

#### Mac y Linux

El software que se enumera a continuación trabaja conjuntamente para
proporcionar un entorno de trabajo con R:

- [Emacs](https://www.gnu.org/software/emacs/) es un IDE potente y
  personalizable quevpuede utilizarse con R, aunque al principio hay que
  aprender muchos comandos.
- [Emacspeak](https://github.com/tvraman/emacspeak) es un lector de
  pantalla diseñado específicamente para su uso en un terminal Linux (o
  Mac) con Emacs.Funciona mucho mejor que VoiceOver, el lector de
  pantalla nativo de Apple, en el terminal.Emacspeak es potente, pero
  también implica aprender muchos comandos de teclado.
- [Estadísticas de Emacs Speaks (ESS)](https://ess.r-project.org) es un
  paquete que puede añadir a Emacs y que le permitirá editar y enviar
  código y ver su resultado en otra ventana de texto.Personaliza el
  entorno emacs para R.
- Otro paquete emacs útil es [Polymode](https://polymode.github.io) que
  facilita el uso de R Markdown para producir documentos como informes y
  diapositivas que son muy accesibles si se usan en formato HTML.

La última vez que probé VScode en un Mac, no era totalmente accesible
con VoiceOver.

## Funciones útiles de R

R Markdown y `quarto` son herramientas útiles de R.Permiten crear un
único archivo que contiene texto y código R.El documento resultante
puede mostrar tanto la explicación de texto de tu trabajo como la salida
del codigo de R.Estas herramientas producen varios tipos de archivos
como salida.La salida HTML es fácil de navegar de forma similar a la de
los colegas videntes.Esta accesibilidad hace que estas herramientas sean
ideales para informes, tareas, sitios web y presentaciones de
diapositivas.

No he incluido documentación aquí porque es difícil encontrar
documentación que no asuma el uso de RStudio.

## Aprender a usar R

Es importante practicar leyendo y aprendiendo de la documentación de R,
pero lleva tiempo aprender a entenderla. Hay un montón de recursos
útiles disponibles, incluyendo:

- UCLA tiene muy buenos [módulos de aprendizaje y preguntas
  frecuentes](https://stats.oarc.ucla.edu/r/) sobre R en formato de
  texto sencillo.
- Buscar en la Web ejemplos y tutoriales (siempre que no sean vídeos)
  para el tipo de análisis que quieres hacer puede ayudar mucho. Evita
  los sitios comerciales con muchos anuncios que interfieren con la
  navegación del lector de pantalla. Yo prefiero los alojados en sitios
  personales o académicos.
- [Sitio web de Oscar Baruffa](https://www.bigbookofr.com) enumera
  libros gratuitos en línea sobre R. Muchos de ellos son bastante
  accesibles, salvo en lo que respecta a las visualizaciones de datos.
  Además, muchos de ellos asumen que estás usando RStudio, por lo que
  tendrás que adaptar el trabajo a tu propio entorno.
- [Bookshare](https://bookshare.org) es un repositorio de libros
  electrónicos para personas con dificultades para leer libros impresos
  en algunos paises. Tienen muchos libros sobre R, pero la accesibilidad
  puede variar, por ejemplo, a veces faltan fragmentos de código. Sin
  embargo, estos libros pueden ser bastante útiles.

## Resumen

En esta guía se han descrito varias formas de que las personas que usan
lectores de pantalla trabajen con R en distintos sistemas operativos,
destacando herramientas accesibles como BrailleR, VS Code y Emacs. Al
explorar estas opciones, los usuarios pueden elegir las herramientas que
mejor se adapten a sus necesidades y preferencias.


Hace poco [Yanina Bellini Saibene](/author/yanina-bellini-saibene/) nos
recordó actualizar el perfil de Slack:

> Recordatorio amigable: Aumentemos el valor de nuestra comunidad de
> Slack de rOpenSci. Por favor, agreguen detalles a su perfil, como su
> foto, su red social favorita, lo que hacen, sus pronombres y cómo se
> pronuncia su nombre.

Después de hacer eso, decidí actualizar mis fotos de perfil en el sitio
web de rOpenSci, y termine aprendiendo algunos trucos de git que voy a
compartir acá. Gracias a [Maëlle Salmon](/author/ma%C3%ABlle-salmon/)
por motivarme a escribir este artículo y a [Steffi
LaZerte](/author/steffi-lazerte/) por revisarlo.

## Clonando como siempre

Cuando quise clonar el repositorio del sitio web de rOpenSci, me di
cuenta de que era grande y que me llevaría varios minutos.

::: {.highlight}
``` {.chroma tabindex="0"}
git clone https://github.com/ropensci/roweb3.git
```
:::

Decidí detener el proceso e investigar cómo clonar solo la última
versión de los archivos específicos que necesitaba.

## Clonando la última versión de archivos específicos

Primero hice un *fork* (bifurcación) del repositorio (`roweb3`). Usé
[`gh`](https://cli.github.com/) desde la terminal, pero también podría
haberlo hecho manualmente desde GitHub.

::: {.highlight}
``` {.chroma tabindex="0"}
# Si no usas `gh`, hace un "fork" de ropensci/roweb3 desde GitHubgh repo fork ropensci/roweb3
```
:::

Luego creé un directorio local vacío `roweb3` y lo enlacé al *fork*.

::: {.highlight}
``` {.chroma tabindex="0"}
git init roweb3cd roweb3git remote add origin git@github.com:maurolepore/roweb3.git
```
:::

¡Ahora los trucos! Para evitar descargar todo el repositorio primero
encontre los archivos específicos que necesitaba en el buscador de
GitHub (*Go to file*), luego:

- Truco 1: Configuré un [*sparse
  checkout*](https://git-scm.com/docs/git-sparse-checkout) para clonar
  solo esos archivos.

::: {.highlight}
``` {.chroma tabindex="0"}
git config core.sparseCheckout trueecho "themes/ropensci/static/img/team/mauro*" >> .git/info/sparse-checkout
```
:::

- Truco 2: Usé `git pull` con
  [`--depth 1`](https://git-scm.com/docs/git-pull#Documentation/git-pull.txt---depthltdepthgt)
  para obtener solo la última versión de esos archivos.

::: {.highlight}
``` {.chroma tabindex="0"}
git pull --depth=1 origin main
```
:::

Exploré el resultado con
[`tree`](https://manpages.ubuntu.com/manpages/bionic/man1/tree.1.html) y
vi que era justo lo que necesitaba modificar:

::: {.highlight}
``` {.chroma tabindex="0"}
tree.└── themes    └── ropensci        └── static            └── img                └── team                    ├── mauro-lepore.jpg                    └── mauro-lepore-mentor.jpg
```
:::

## ¿Pero qué tan grande es?

Aunque esos trucos fueron útiles, aún quería saber cuán grande era el
repositorio, así que lo cloné entero como de costumbre y lo exploré con
[`du`](https://manpages.ubuntu.com/manpages/bionic/man1/du.1.html):

::: {.highlight}
``` {.chroma tabindex="0"}
du --human-readable --max-depth=1 .219M    ./themes164K    ./.Rproj.user56K     ./archetypes628K    ./resources168K    ./data376M    ./.git20K     ./static12K     ./.github40K     ./scripts161M    ./content24K     ./layouts475M    ./public1.3G    .
```
:::

Esto confirmó que el repositorio es mucho más grande que los que manejo
normalmente. Pero ahora sé algunos trucos más de Git (¡y aún más sobre
cómo bloguear en rOpenSci :-)).

## Conclusión

> Si todo lo que tienes es un martillo, todo te parecerá un clavo. ---
> Abraham Maslow

A veces, `git clone` no es la herramienta adecuada para el trabajo que
querés hacer. Un *sparse checkout* y un *pull* superficial pueden
ayudarte a obtener específicamente lo que necesitas.

Si te gusta aprender de videos, podés [buscar "git" en mi canal de
YouTube](https://www.youtube.com/leporemauro/search?query=git) o
explorar las listas de reproducción
[git](https://www.youtube.com/playlist?list=PLvgdJdJDL-AOHkwiaMvYhPKVjiD9vzZIo),
[git-from-the-terminal](https://www.youtube.com/playlist?list=PLvgdJdJDL-AMyv06bsXoXkGmxmaV9U6Ts),
y
[git-con-la-terminal](https://www.youtube.com/playlist?list=PLvgdJdJDL-APwLSt89PJgI72UGVNUjOKl).

¿Cuáles son tus trucos favoritos de Git? ¿Qué tal si blogueas sobre eso?


Como parte de nuestro [proyecto editorial
multilingüe](/multilingual-publishing/) y con [financiación del
Consorcio
R](https://www.r-consortium.org/all-projects/awarded-projects/2022-group-2)
hemos trabajado en el paquete R
[babeldown](https://docs.ropensci.org/babeldown/) para traducir
contenido basado en Markdown utilizando la API de DeepL.En esta nota
técnica, mostraremos cómo puedes utilizar babeldown para traducir un
artículo de blog que utiliza Hugo.

## Motivación

Traducir un artículo de blog en Markdown desde tu consola de R no sólo
es más cómodo (cuando ya has escrito dicho artículo en R), sino también
menos frustrante.Con babeldown, en comparación con copiar y pegar el
contenido del artículo en algún servicio de traducción, no se romperá la
sintaxis Markdown^[1](#fn:1){.footnote-ref role="doc-noteref"}^, ni se
traducirán las líneas de código.Esto funciona porque, detrás de escena,
babeldown utiliza [tinkr](https://docs.ropensci.org/tinkr) para producir
XML que luego envía a la API DeepL, marcando algunas etiquetas como no
traducibles. A continuación, convierte el XML traducido por DeepL de
nuevo en Markdown.

Ahora bien, como era de esperar, ¡este contenido traducido por la
máquina aún no es perfecto!Aún necesitarás una o dos personas para
revisar y corregir la traducción.Entonces, ¿por qué no hacer que una
persona traduzcan el artículo desde cero?Hemos observado que para las
personas voluntarias que participan en nuestras traduciones, editar una
traducción automática es más rápido que traducir todo el artículo, y que
libera espacio mental para centrarse en la aplicación de reglas de
traducción como la redacción neutra en cuanto al género.

## Configuración

### Requisitos previos en el sitio web de Hugo

[`babeldown::deepl_translate_hugo()`](https://docs.ropensci.org/babeldown/reference/deepl_translate_hugo.html)
asume que el sitio web de Hugo utiliza

- grupo de hojas (cada artículo en una carpeta,
 `content/camino-a-la-hoja/index.md`);
- multilingüismo para que un post en (por ejemplo) español viva en
 `content/camino-a-la-hoja/index.es.md`.

babeldown podría ampliarse para funcionar con otras configuraciones
multilingües de Hugo. Si estás interesado en utilizar babeldown con una
configuración diferente, ¡ abre un *issue* en la sección correspondiente
en el [repositorio de
babeldow](https://github.com/ropensci-review-tools/babeldown/)!

Ten en cuenta que babeldown no podrá determinar el idioma por defecto de
tu sitio web^[2](#fn:2){.footnote-ref role="doc-noteref"}^, así que
aunque el idioma por defecto de tu sitio web sea el inglés, babeldown
colocará una traducción al inglés en un archivo llamado ".en.md" y no
".md".Hugo reconocerá el nuevo archivo igualmente (al menos en nuestra
configuración).

### Requisitos previos de DeepL

Comprueba primero que la API DeepL admite los idiomas de origen y
destino que desees.Busca la [documentación de los parámetros
`source_lang` y `target_lang` de la
API](https://www.deepl.com/docs-api/translate-text) para obtener una
lista completa.

Una vez que sepas que podrás aprovechar la API de DeepL, tendrás que
crear una cuenta para [la API del servicio de traducción de
DeepL](https://www.deepl.com/en/docs-api/).Ten en cuenta que incluso
para obtener una cuenta gratuita es necesario registrar un método de
pago con ellos.

### Requisitos previos de R

Necesitarás instalar babeldown desde el Universo R de rOpenSci:

::: {.highlight}
``` {.chroma tabindex="0"}
install.packages('babeldown', repos = c('https://ropensci.r-universe.dev', 'https://cloud.r-project.org'))
```
:::

A continuación, en cada sesión de R, establece tu clave de API DeepL
mediante la variable de entorno DEEPL_API_KEY. Puedes almacenarla de una
vez por todas con el paquete
[keyring](https://r-lib.github.io/keyring/index.html) y recuperarla en
tus scripts de la siguiente manera:

::: {.highlight}
``` {.chroma tabindex="0"}
Sys.setenv(DEEPL_API_KEY = keyring::key_get("deepl"))
```
:::

Por último, la URL de la API DeepL depende de tu plan.babeldown utiliza
por defecto la URL de API gratuita DeepL.Si utilizas un plan Pro,
establece la URL de la API en cada sesión/script de R mediante

::: {.highlight}
``` {.chroma tabindex="0"}
Sys.setenv("DEEPL_API_URL" = "https://api.deepl.com")
```
:::

## ¡Traducción!

Puedes ejecutar el siguiente código:

::: {.highlight}
``` {.chroma tabindex="0"}
babeldown::deepl_translate_hugo( post_path = <path-to-post>, source_lang = "EN", target_lang = "ES", formality = "less" # that's how we roll here!)
```
:::

pero te recomendamos que trabajes un poco más por tu propio bien.

## Traducción utilizando un flujo de trabajo Git/GitHub

Si utilizas el control de versiones, ¡tener la traducción como un diff
es muy práctico!

### Primero: En palabras e imágenes

- En la rama de tu artículo (llamémosla "new-post") crea un marcador de
 posición: guarda tu artículo original del blog (`index.es.md`) bajo el
 nombre del artículo de destino (`index.en.md`) haz *commit* y luego
 *push*.

<figure>
<img src="placeholder.png"
alt="Diagrama de dos partes. A la izquierda una carpeta de hojas de Hugo en la rama new-post con el artículo en español con el texto &#39;Hola&#39; y una imagen; a la derecha la carpeta de hojas de Hugo en la misma rama con el post en español con el texto &#39;Hola&#39;, el post con el nombre de archivo de destino en inglés con el texto &#39;Hola&#39;, y la imagen." />
</figure>

- Crea una nueva rama, "auto-traducción" por ejemplo.
- Ejecuta `babeldown::deepl_translate_hugo()` con `force = TRUE`.

<figure>
<img src="translate.png"
alt="Diagrama con dos partes. A la izquierda la carpeta de hojas de Hugo en la rama de auto-translate con el artículo en español con el texto &#39;Hola&#39;, el post con el nombre de archivo de destino en inglés con el texto &#39;Hola&#39;, y la imagen; a la derecha lo único que cambió es que el contenido del post con el nombre de archivo de destino en inglés es ahora &#39;Hello&#39;." />
</figure>

- *Commit* y *push* el resultado.
- Abre un PR desde el **"translation-tech-note"** a la rama
 **"new-post"**.La única diferencia entre las dos ramas es la
 traducción automática de tu artículo. La diferencia para el artículo
 de destino será la diferencia entre los idiomas de origen y de
 destino. Si tienes la buena costumbre de empezar una nueva línea
 después de cada frase/parte de una frase, aún mejor.

<figure>
<img src="pr.png"
alt="Dibujo del pull request de la rama auto-translate a la rama new-post donde la diferencia es que ahora se ha traducido al inglés el contenido de la entrada con el nombre de archivo de destino en inglés." />
</figure>

- Las personas que traducen o revisan pueden abrir un segundo PR en la
 rama de traducción con sus ediciones. O pueden añadir sus ediciones
 como
 [sugerencias](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-comments-to-a-pull-request).

### De nuevo pero en código

Ahora vamos a repasar esto de nuevo, pero con un flujo de trabajo de
programación. Utilizaremos fs y gert (¡pero hazlo como mejor te resulte
a ti!). Suponemos que tu directorio actual es la raíz de la carpeta del
sitio web, y también la raíz del repositorio git.

- En la rama del artículo, (de nuevo, llamémosla "new-post"), guarda tu
 artículo original del blog (`index.es.md`) con el nombre del artículo
 de blog de destino (`index.en.md`). Haz *commit* y luego *push*.

::: {.highlight}
``` {.chroma tabindex="0"}
fs::file_copy( file.path("content", "blog", "2023-10-01-r-universe-interviews", "index.es.md"), file.path("content", "blog", "2023-10-01-r-universe-interviews", "index.en.md"))gert::git_add(file.path("content", "blog", "2023-10-01-r-universe-interviews", "index.en.md"))gert::git_commit("Add translation placeholder")gert::git_push()
```
:::

- Crea una nueva rama, "auto-translate" por ejemplo.

::: {.highlight}
``` {.chroma tabindex="0"}
gert::git_branch_create("translation-tech-note")
```
:::

- Ejecuta `babeldown::deepl_translate_hugo()` con `force = TRUE`.

::: {.highlight}
``` {.chroma tabindex="0"}
babeldown::deepl_translate_hugo( post_path = file.path("content", "blog", "2023-10-01-r-universe-interviews", "index.es.md"), force = TRUE, yaml_fields = c("title", "description", "tags"), source_lang = "ES", target_lang = "EN-US")
```
:::

También puedes omitir `post_path` si estás ejecutando el código desde la
IDE de RStudio y si el archivo abierto y en foco (el que ves encima de
tu consola) es el post que hay que traducir.

::: {.highlight}
``` {.chroma tabindex="0"}
babeldown::deepl_translate_hugo( force = TRUE, yaml_fields = c("title", "description", "tags"), source_lang = "ES", target_lang = "EN-US")
```
:::

- Haz *commit* del resultado con el código que aparece a continuación.

::: {.highlight}
``` {.chroma tabindex="0"}
gert::git_add(file.path("content", "blog", "2023-10-01-r-universe-interviews", "index.en.md"))gert::git_commit("Add translation")gert::git_push()
```
:::

- Abre un PR desde el **"translation-tech-note"** a la rama
 **"new-post"**.La única diferencia entre las dos ramas es la
 traducción automática de
 `"content/blog/2023-10-01-r-universe-interviews/index.en.md"`.

- Las personas que traducen o revisan pueden entonces ¡abrir un
 *segundo* PR a la rama de traducción con sus ediciones! O pueden
 añadir sus ediciones como
 [sugerencias](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-comments-to-a-pull-request).

### Resumen de ramas y PRs

Al final debería haber dos o tres ramas:

- branch A con artículo en español y marcador de posición de artículo en
 inglés (con contenido en español) -- PR to main;
- rama B con el artículo traducido automáticamente al inglés -- PR a la
 rama A;
- Opcionalmente, la rama C con la edición de una persona de la
 traducción automática al inglés del artículo -- PR a la rama B. Si la
 rama C no existe, las ediciones realizadas por una persona se hacen
 como sugerencias de revisión de PR en el PR de B a A.

Los PR se fusionan en este orden:

- PR a la rama B;
- PR a la rama A;
- PR a main.

### Ejemplo real

- [PR añadiendo un artículo al blog de
 rOpenSci](https://github.com/ropensci/roweb3/pull/629), observa que es
 un PR del **"r-universe-interviews"** a la rama **"main" (por
 defecto)**;
- [PR añadiendo la traducción
 automática](https://github.com/ropensci/roweb3/pull/639), observa que
 es un PR para la rama **"r-universe-interviews"**.

<figure>
<img src="pr-diff.png"
alt="Captura de pantalla de la pestaña de archivos del pull request que añade la traducción automática, donde observamos que el texto en español de los metadatos YAML y el contenido Markdown se ha traducido al inglés." />
</figure>

Yanina retocó la traducción automática sugiriendo cambios en el PR, y
luego aceptándolos.

<figure>
<img src="pr-comments.png"
alt="Captura de pantalla de la pestaña principal del pull request que añade la traducción automática, donde observamos un comentario de Yanina sustituyendo la palabra &#39;artículo&#39; por &#39;entrada de blog&#39; y arreglando el nombre de &#39;R-universo&#39;." />
</figure>

### Campos YAML

Por defecto, babeldown traduce los campos YAML "título" y
"descripción".Si tienes texto en más campos, utiliza la opción
`yaml_fields` argumento de `babeldown::deepl_translate_hugo()`.

Ten en cuenta que si babeldown traduce el título, actualiza el slug.

### Glosario

Imagina que tienes algunas preferencias para algunas palabras, algo que
irás construyendo con el tiempo.

::: {.highlight}
``` {.chroma tabindex="0"}
readr::read_csv( system.file("example-es-en.csv", package = "babeldown"), show_col_types = FALSE)
```
:::

``` {tabindex="0"}
## # A tibble: 2 × 2## Spanish English ## <chr> <chr> ## 1 paquete package ## 2 repositorio repository
```

Puedes registrar estas traducciones preferidas en un glosario en tu
cuenta de DeepL.

::: {.highlight}
``` {.chroma tabindex="0"}
deepl_upsert_glossary( <path-to-csv-file>, glossary_name = "rstats-glosario", target_lang = "Spanish", source_lang = "English")
```
:::

Utilizarías exactamente el mismo código para *actualizar* el glosario,
de ahí el nombre "upsert" de la función.Necesitas un glosario por cada
par de idiomas de origen y destino: el glosario inglés-español no puede
utilizarse, por ejemplo, para el español-inglés.

En tu `babeldown::deepl_translate_hugo()` llamada utilizarás el nombre
del glosario (aquí "rstats-glosario") para el argumento `glossary`.

### Formalidad

`deepl_translate_hugo()` tiene un `formality` argumento.Ahora bien, la
API de DeepL sólo admite esto para algunos idiomas, como se explica en
el apartado de la [documentación del parámetro `formality` de la
API](https://www.deepl.com/docs-api/translate-text):

> Establece si el texto traducido debe inclinarse hacia un lenguaje
> formal o informal. Actualmente, esta opción sólo funciona para las
> lenguas de destino DE (alemán), FR (francés), IT (italiano), ES
> (español), NL (neerlandés), PL (polaco), PT-BR y PT-PT (portugués), JA
> (japonés) y RU (ruso). (...) La configuración de este parámetro con
> una lengua de destino que no admita la formalidad fallará, a menos que
> se utilice una de las opciones prefer\_...

Por tanto, para asegurarnos de que una traducción funcionará, en lugar
de escribir `formality = "less"` puedes escribir
`formality = "prefer_less"` que sólo utilizará la formalidad si está
disponible.

## Conclusión

En este post hemos explicado cómo traducir una entrada del blog de Hugo
utilizando babeldown.Aunque lo esencial es utilizar una llamada a
`babeldown::deepl_translate_hugo()`,

- es necesario indicar la URL de la API y la clave,
- se pueden mejorar los resultados utilizando los distintos argumentos
 de la función,
- recomendamos emparejar la traducción con un flujo de trabajo Git +
 GitHub (o GitLab, gitea...).

babeldown tiene
[funciones](https://docs.ropensci.org/babeldown/reference/index.html)
para traducir capítulos de libros Quarto, cualquier archivo Markdown y
cualquier cadena Markdown, con argumentos similares y uso recomendado,
¡así que explora su referencia!

Nos encantaría que nos cuentes tus [casos de uso](/usecases/).

::: {.footnotes role="doc-endnotes"}

------------------------------------------------------------------------

1. ::: {#fn:1}
 Pero deberías consultar [tinkr
 docs](https://docs.ropensci.org/tinkr/#loss-of-markdown-style) para
 ver qué puede cambiar en el estilo de sintaxis
 Markdown. [↩︎](#fnref:1){.footnote-backref role="doc-backlink"}
 :::

2. ::: {#fn:2}
 añadir código para manejar la ["desconcertante variedad de posibles
 ubicaciones de
 configuración"](https://github.com/r-lib/hugodown/issues/14#issuecomment-632850506)
 de Hugo y dos formatos posibles (YAML y TOML) está fuera del alcance
 de babeldown en este momento. [↩︎](#fnref:2){.footnote-backref
 role="doc-backlink"}
 :::
:::