Multilingualism tools for rOpenSci

Maëlle Salmon, rOpenSci

What we had at the beginning

  • A guide as a Quarto book;

  • Interest in using DeepL API;

  • Use of Git and GitHub to collaborate.

https://babel-en.netlify.app/

Picture by MART PRODUCTION on Pexels.

papél con las palabras 'TO DO'

What we were missing

  • How to publish a multilingual Quarto book;

  • How to use DeepL API to translate Markdown.

Picture by Miro Vrlik on Pexels.

herramientas como tijeras

Multilingual Quarto book: babelquarto

First we made sure that it would not be native to Quarto very soon: https://github.com/quarto-dev/quarto-cli/issues/275

Picture by Anna Shvets on Pexels.

'?' dibujado con perlas

Our first multilingual Quarto book

https://devdevguide.netlify.app/

Screenshot of the rOpenSci dev guide, development version

Multilingual books with babelquarto

Each chapter: filepath.qmd and filepath.es.qmd.

  • babelquarto::register_main_language("en")

  • babelquarto::register_further_languages(c("es", "pt"))

  • babelquarto::render_book()

_quarto.yml

With the help of babelquarto::register_,

babelquarto:
  mainlanguage: en
  languages: ['es', 'pt']
title-es: title in es
description-es: description in es
author-es: author in es
title-pt: title in pt
description-pt: description in pt
author-pt: author in pt

Multilingual websites: Quarto

https://www.joelnitta.com/

Screenshot from Joel Nitta’s Japanese website

How babelquarto works

  • Build the two sites.

  • Add links with {xml2} XPath to modify HTML.

How to translate Markdown

  • Translating Markdown from scratch? 😭

  • Copy and paste into DeepL or Google Translate? 😭

  • Use babeldown and then review by humans! 🎉

Translate Markdown with babeldown

  • Respect the Markdown format.

  • Send text to the DeepL API.

Picture by Heiner on Pexels.

buzón

Use babeldown

  • Register with DeepL.

  • Hello World.

Sys.setenv(DEEPL_API_KEY = keyring::key_get("deepl"))
Sys.setenv("DEEPL_API_URL" = "https://api.deepl.com")
babeldown::deepl_translate_markdown_string(
  "Je suis contente d'être à **Barcelone**",
  source_lang = "fr",
  target_lang = "en-us",
  formality = "prefer_less"
)
[1] "I'm happy to be at **Barcelona**"

How babeldown works

  • Transform Markdown to XML using {tinkr} ({commonmark} + {xml2} + {xslt}).
  • Protects some things (Hugo shortcodes).
  • Send XML to the API of DeepL.
  • It also sends YAML snippets to the DeepL API.
  • Create Markdown again.

Using babeldown, with git and GitHub (1/3)

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 'Hola' 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 'Hola', el post con el nombre de archivo de destino en inglés con el texto 'Hola', y la imagen.

Using babeldown, with git and GitHub (2/3)

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 'Hola', el post con el nombre de archivo de destino en inglés con el texto 'Hola', 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 'Hello'.

Using babeldown with git and GitHub (3/3)

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.

What remains to be done

  • Better support of multilingual websites with babelquarto;

  • Use of git diff with babeldown.

What you can already try