Maëlle Salmon

Yanina Bellini Saibene

Dans le cadre de notre [projet d'édition multilingue](/multilingual-publishing/) et avec un [financement du R Consortium](https://www.r-consortium.org/all-projects/awarded-projects/2022-group-2) nous avons travaillé sur le paquet R [babeldown](https://docs.ropensci.org/babeldown/) pour la traduction de contenu Markdown à l'aide de l'API DeepL.Dans cette note technique, nous allons montrer comment on peut utiliser babeldown pour traduire un article de blog Hugo !

## Motivation

Traduire un article de blog en Markdown depuis la console R est non seulement plus confortable (quand on a déjà écrit ledit article de blog en R), mais aussi moins frustrant.Avec babeldown, comparé au copier-coller du contenu d'un billet de blog dans un quelconque service de traduction, la syntaxe Markdown ne sera pas cassée^[1](#fn:1){.footnote-ref role="doc-noteref"}^, et les morceaux de code ne seront pas traduits.Cela fonctionne, car en pratique, babeldown utilise [tinkr](https://docs.ropensci.org/tinkr) pour produire du XML qu'il envoie ensuite à l'API DeepL, en signalant certaines balises comme ne devant pas être traduites. Il convertit ensuite le XML traduit par DeepL en Markdown.

Comme on peut s'en douter, ce contenu traduit automatiquement n'est pas encore parfait !Il faudra encore le travail d'un ou deux humains pour réviser et modifier la traduction.Pourquoi ne pas demander aux humains de traduire l'article à partir de zéro ?Nous avons observé que l'édition d'une traduction automatique est plus rapide que la traduction de l'ensemble du billet, et qu'elle libère de l'espace mental pour se concentrer sur la mise en œuvre de règles de traduction telles que la formulation non sexiste.

## Configuration

### Pré-requis sur le site Hugo

[`babeldown::deepl_translate_hugo()`](https://docs.ropensci.org/babeldown/reference/deepl_translate_hugo.html) suppose que le site web Hugo utilise

-   "leaf bundles" (chaque post dans un dossier, `content/path-to-leaf-bundle/index.md`) ;
-   le multilinguisme, de sorte qu'un message en espagnol se retrouve dans par exemple) `content/path-to-leaf-bundle/index.es.md`.

babeldown pourrait être étendu à d'autres configurations multilingues Hugo. Si vous souhaitez utiliser babeldown avec une configuration différente, ouvrez une "issue" dans le [dépôt de babeldown](https://github.com/ropensci-review-tools/babeldown/)!

À noter, babeldown ne pourra pas déterminer la langue par défaut du site web^[2](#fn:2){.footnote-ref role="doc-noteref"}^ donc même si la langue par défaut du site web est l'anglais, babeldown placera une traduction anglaise dans un fichier appelé ".en.md" et non ".md".Hugo reconnaîtra tout de même le nouveau fichier (du moins dans notre configuration).

### Pré-requis DeepL

Il faut d'abord vérifier que les langues source et cible souhaitées sont prises en charge par l'API DeepL !On peut se référer à la documentation des [paramètres de l'API `source_lang` et `target_lang`](https://www.deepl.com/docs-api/translate-text) pour une liste complète.

Une fois sûr·e qu'on peut profiter de l'API DeepL, il faut créer un compte pour [l'API du service de traduction DeepL](https://www.deepl.com/en/docs-api/).Même l'obtention d'un compte gratuit nécessite l'enregistrement d'un moyen de paiement auprès d'eux.

### Pré-requis R

Commençons par installer babeldown à partir de l'univers R de rOpenSci :

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

Ensuite, dans chaque session R, on définit sa clé API DeepL via la variable d'environnement `DEEPL_API_KEY`.On peut l'enregistrer une fois pour toutes avec le paquet [keyring](https://r-lib.github.io/keyring/index.html) et la récupérer dans les scripts comme suit :

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

Enfin, l'URL de l'API DeepL dépend de votre plan API.babeldown utilise par défaut l'URL d'API gratuite DeepL.Quand on utilise un plan Pro, on doit définir l'URL de l'API dans chaque session/script R via

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

## Traduction ! {#traduction-}

On pourrait exécuter le code ci-dessous

::: 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!)
```
:::

mais nous recommandons d'en faire un peu plus pour de meilleurs résultats.

## Traduction à l'aide d'un flux de travail Git/GitHub

Quand on utilise le contrôle de version, avoir la traduction sous forme de diff est très pratique !

### Premièrement : En mots et en images {#premièrement--en-mots-et-en-images}

-   Dans la branche de l'article à traduire (appelons-la "new-post"), on crée un fichier pour "garder la place", en enregistrant l'article de blog original (`index.es.md`) sous le nom de l'article cible (`index.en.md`) et en faisait un Git commit et un Git push.

![Diagramme avec à gauche le dossier \'leaf\' dans la branche new-post avec l\'article en espagnol avec le texte \'Hola\' et une image ; à droite le dossier \'leaf\' dans la branche new-post avec l\'article en espagnol avec le texte \'hola\', l\'article avec le nom de fichier cible en anglais avec le texte \'hola\', et l\'image.](placeholder.png)

-   Ensuite on crée une nouvelle branche, "auto-translate" par exemple.
-   Puis on exécute `babeldown::deepl_translate_hugo()` avec `force = TRUE`.

![Diagramme avec à gauche le dossier \'leaf\' dans la branche de traduction automatique avec l\'article en espagnol avec le texte \'hola\', l\'article avec le nom de fichier cible en anglais avec le texte \'hola\', et l\'image ; à droite la seule chose qui a changé est que le contenu de l\'article avec le nom de fichier cible en anglais est maintenant \'hello\'.](translate.png)

-   Git commit et Git push le résultat.
-   On ouvre alors une PR à partir de la page **"auto-translate"** à la branche **"new-post"**.La seule différence entre les deux branches est la traduction automatique du billet. La Git diff pour l'article de blog cible sera la différence entre la langue source et la langue cible ! En ayant la bonne habitude de commencer une nouvelle ligne après chaque phrase / partie de phrase, c'est encore mieux.

![Dessin de la pull request de la branche auto-translate vers la branche new-post où la différence est que le contenu du post avec le nom de fichier cible anglais a maintenant été traduit en anglais.](pr.png)

-   Les traducteur·rice·s humain·e·s peuvent alors ouvrir une deuxième PR à la branche de traduction avec leurs modifications ! Ou il·elle·s peuvent ajouter leurs modifications en tant que [suggestions de PR](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).

### Encore une fois : En code {#encore-une-fois--en-code}

Reprenons l'exercice, mais avec des exemples de code. Ici, nous utiliserons fs et gert (mais à chacun·e ses outils favoris !), et nous supposerons que le répertoire courant est la racine du dossier du site Web, et aussi la racine du dépôt Git.

-   Dans la branche post, (encore une fois, appelons-la "new-post"), enregistrer l'article de blog original (`index.es.md`) sous le nom de l'article cible (`index.en.md`) et Git commit et Git 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()
```
:::

-   Créer une nouvelle branche, "translation-tech-note" par exemple.

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

-   Exécuter `babeldown::deepl_translate_hugo()` avec `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")
```
:::

On peut aussi omettre le `post_path` si on exécute le code à partir de l'IDE RStudio et si le fichier ouvert et focalisé (celui que l'on voit au-dessus de la console) est le billet à traduire.

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

-   Git commit et Git push le résultat avec le code ci-dessous.

::: 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()
```
:::

-   Ouvrir une PR à partir de la page **"translation-tech-note"** à la branche **"new-post"**.La seule différence entre les deux branches est la traduction automatique de `"content/blog/2023-10-01-r-universe-interviews/index.en.md"`.

-   Les traducteur·rice·s humains peuvent alors a ouvrir une *deuxième* PR à la branche de traduction avec leurs modifications ! Ou il·elle·s peuvent ajouter leurs modifications en tant que [suggestions de RP](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).

### Résumé des branches et des PR

Au final, il devrait y avoir deux ou trois branches :

-   branche A avec un article de blog en espagnol et un article de blog de remplacement pour l'anglais (avec un contenu espagnol) -- PR vers la branche défaut (main) ;
-   branche B avec un article de blog traduit automatiquement en anglais -- PR vers la branche A ;
-   Optionnellement, branche C avec la traduction automatique en anglais de l'article de blog éditée par un humain -- PR vers la branche B. Si la branche C n'existe pas, les éditions par un humain sont faites en tant que suggestions de révision PR dans le PR de B à A.

Les PR sont fusionnées dans cet ordre :

-   PR vers la branche B ;
-   PR vers la branche A ;
-   PR vers la branche principale.

### Exemple réel

-   [PR ajoutant un article au blog rOpenSci](https://github.com/ropensci/roweb3/pull/629). Il s'agit d'un PR du blog rOpenSci **"r-univers-interviews"** à la branche **"main" (par défaut)** ;
-   [PR ajoutant la traduction automatique](https://github.com/ropensci/roweb3/pull/639). Il s'agit d'un PR vers la branche **"r-universe-interviews"** .

![Capture d\'écran de l\'onglet files de la pull request ajoutant la traduction automatique, où l\'on observe que le texte espagnol dans les métadonnées YAML et le contenu Markdown a été traduit en anglais.](pr-diff.png)

Yanina a peaufiné la traduction automatique en suggérant des changements sur la PR, puis en les acceptant.

![Capture d\'écran de l\'onglet principal de la pull request ajoutant la traduction automatique, où l\'on observe un commentaire de Yanina remplaçant le mot \'article\' par \'blog post\' et fixant le nom de \'R-universe\'.](pr-comments.png)

### Champs YAML

Par défaut, babeldown traduit les champs YAML "title" et "description".S'il y a du texte dans d'autres champs, il faut utiliser l'argument `yaml_fields` de `babeldown::deepl_translate_hugo()`.

Si babeldown traduit le titre, il met à jour le slug.

### Glossaire

Imaginons avoir quelques préférences pour certains mots -- quelque chose que l'on accumule au fil du temps.

::: 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
```

On peut enregistrer ces traductions préférées dans un glossaire sur notre compte DeepL.

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

On utilisera exactement le même code pour *mettre à jour* le glossaire, d'où le nom "upsert" de la fonction.Il faut un glossaire par paire langue source / langue cible : le glossaire anglais-espagnol ne peut pas être utilisé pour l'espagnol vers l'anglais par exemple.

Dans l'appel `babeldown::deepl_translate_hugo()` on utilise alors le nom du glossaire (ici "rstats-glosario") pour la paire de langues source et cible. `glossary` argument.

### Formalité

`deepl_translate_hugo()` a un argument `formality`.Or, l'API DeepL ne prend en charge que certaines langues, comme l'explique la documentation du [paramètre `formality` de l'API](https://www.deepl.com/docs-api/translate-text):

> Définit si le texte traduit doit pencher vers un langage formel ou informel. Cette fonction ne fonctionne actuellement que pour les langues cibles DE (allemand), FR (français), IT (italien), ES (espagnol), NL (néerlandais), PL (polonais), PT-BR et PT-PT (portugais), JA (japonais) et RU (russe). (...) Le réglage de ce paramètre avec une langue cible qui ne prend pas en charge la formalité échouera, à moins que l'une des options prefer\_... ne soit utilisée.

Par conséquent, pour être sûr qu'une traduction fonctionnera, au lieu d'écrire `formality = "less"` il faut écrire `formality = "prefer_less"` qui n'utilisera la formalité que si elle est disponible.

## Conclusion

Dans ce billet, nous avons expliqué comment traduire un article de blog Hugo à l'aide de babeldown.Bien que l'essentiel soit d'utiliser un appel à `babeldown::deepl_translate_hugo()`,

-   il faut indiquer l'URL et la clé de l'API,
-   on peut améliorer les résultats en utilisant les différents arguments de la fonction,
-   nous recommandons d'associer la traduction à un flux de travail Git + GitHub (ou GitLab, gitea...).

babeldown a des [fonctions](https://docs.ropensci.org/babeldown/reference/index.html) pour traduire les chapitres de livres Quarto, n'importe quel fichier Markdown et n'importe quelle chaîne de caractères Markdown, avec des arguments et une utilisation recommandée similaires, alors explorez sa référence !

Nous serions ravis d'entendre parler de vos [cas d'utilisation](/usecases/).

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

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

1.  ::: {#fn:1}
    Mais il faut se référer à la [documentation de tinkr](https://docs.ropensci.org/tinkr/#loss-of-markdown-style) pour voir ce qui pourrait changer dans le style de syntaxe Markdown. [↩︎](#fnref:1){.footnote-backref role="doc-backlink"}
    :::

2.  ::: {#fn:2}
    ajout de code pour gérer l'interface d'Hugo. ["l'ensemble déconcertant d'emplacements de configuration possibles"](https://github.com/r-lib/hugodown/issues/14#issuecomment-632850506) et les deux formats possibles (YAML et TOML) est hors de portée de babeldown pour le moment. [↩︎](#fnref:2){.footnote-backref role="doc-backlink"}
    :::
:::


Dans le cadre de notre projet d’édition multilingue et avec un financement du R Consortium nous avons travaillé sur le paquet R babeldown pour la traduction de contenu Markdown à l’aide de l’API DeepL.Dans cette note technique, nous allons montrer comment on peut utiliser babeldown pour traduire un article de blog Hugo ! Motivation   Traduire un article de blog en Markdown depuis la console R est non seulement plus confortable (quand on a déjà

Comment traduire un billet de blog Hugo avec Babeldown

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"}
    :::
:::


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.

Messaggi di Rogue Scholar

Comment traduire un billet de blog Hugo avec Babeldown

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