diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index 863c2f3..05c99bd 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -41,9 +41,14 @@ jobs: - uses: r-lib/actions/setup-r-dependencies@v2 with: - extra-packages: any::rcmdcheck + extra-packages: | + any::rcmdcheck + any::devtools needs: check + - run: devtools::install(build_vignettes = FALSE) + shell: Rscript {0} + - uses: r-lib/actions/check-r-package@v2 with: upload-snapshots: true diff --git a/.gitignore b/.gitignore index 565f2b6..9b35bd0 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,6 @@ .Rdata .httr-oauth .DS_Store + +docs +vignettes/*_files diff --git a/.lintr b/.lintr index bfcb9a4..ea2d34e 100644 --- a/.lintr +++ b/.lintr @@ -3,4 +3,4 @@ encoding: "UTF-8" exclusions: list( # excluded from all lints: "tests/testthat.R" - ) + ) diff --git a/DESCRIPTION b/DESCRIPTION index d46e6ac..aff448e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -34,3 +34,5 @@ Suggests: URL: https://github.com/ropensci-review-tools/babelquarto BugReports: https://github.com/ropensci-review-tools/babelquarto/issues Config/testthat/edition: 3 +VignetteBuilder: + quarto diff --git a/README.Rmd b/README.Rmd deleted file mode 100644 index 3d093a4..0000000 --- a/README.Rmd +++ /dev/null @@ -1,226 +0,0 @@ ---- -output: github_document ---- - - - -```{r, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>", - fig.path = "man/figures/README-", - out.width = "100%" -) -``` - -# babelquarto - - -[![R-CMD-check](https://github.com/ropensci-review-tools/quartobabel/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci-review-tools/quartobabel/actions/workflows/R-CMD-check.yaml) - - -The goal of babelquarto is to render a Quarto multilingual project, book or website. - -## Installation - -You can install the development version of babelquarto from rOpenSci R-universe: - -```r -install.packages('babelquarto', repos = c('https://ropensci.r-universe.dev', 'https://cloud.r-project.org')) -``` - -Or from [GitHub](https://github.com/) with: - -``` r -# install.packages("pak") -pak::pak("ropensci-review-tools/babelquarto") -``` - -Once using babelquarto, you cannot render your book or website using Quarto CLI (or the RStudio IDE render button) directly. -You need to use `babelquarto::render_book()` or `babelquarto::render_website()`, respectively. - -## Example book - -Create a starter/example book. - -```{r} -parent_dir <- withr::local_tempdir() -project_dir <- "blop" -babelquarto::quarto_multilingual_book(parent_dir = parent_dir, project_dir = project_dir) -readLines(file.path(parent_dir, project_dir, "_quarto.yml")) -fs::dir_tree(file.path(parent_dir, project_dir)) -``` - -```{r, results='hide'} -babelquarto::render_book(file.path(parent_dir, project_dir)) -``` - -We end up with three books, that cross-link to each other from the left sidebar. -[Example](https://devdevguide.netlify.app). - - -## Example website - - -Create a starter/example website. - -```{r} -parent_dir <- withr::local_tempdir() -project_dir <- "blop" -babelquarto::quarto_multilingual_website(parent_dir = parent_dir, project_dir = project_dir) -readLines(file.path(parent_dir, project_dir, "_quarto.yml")) -fs::dir_tree(file.path(parent_dir, project_dir)) -``` - -```{r, results='hide'} -babelquarto::render_website(file.path(parent_dir, project_dir)) -``` - -[Example](https://maelle.github.io/babelsite), [source](https://github.com/maelle/babelsite) - - -## Configure the base URL - -Use the [usual Quarto field](https://quarto.org/docs/websites/website-tools.html), or use the `site_url` argument of `babelquarto::render_book()`. - -``` -book: - site-url: https://example.com -``` - -## Configure the version text - -If you want the choice to be between, say "English" and "Español" rather than "Version in EN" and "Version in ES", add these fields under the babelquarto YAML key, in `_quarto.yml`: - -```yaml -babelquarto: - languagecodes: - - name: es - text: "Español" - - name: en - text: "English" -``` - -Using `babelquarto::register_main_language()` and `babelquarto::register_further_languages()` will create the boilertemplate for these fields. - -## Configure the language link placement - -The language link menu can be placed in the *sidebar* or in the *navbar*. -To change the placement, use the `languagelinks` field in the babelquarto YAML key, in `_quarto.yml`: - -```yaml -babelquarto: - languagelinks: sidebar -``` - -Beware: depending on the value of `languagelinks`, the corresponding menu needs to be configured. -Books always have a *sidebar*, but websites can have either *navbar* or *sidebar*. See [Quarto documentation](https://quarto.org/docs/websites/website-navigation.html#side-navigation) for more information. - -## Distinct configuration per language - -There are two complementary/overlapping solutions for making the different language versions distinct (different banner, different navbar for instance): - -### Configuration file per language - -For a book with French ("fr") and English ("en") versions you could have three Quarto configuration files: - -- `_quarto.yml` with the general configuration including the chapters list; -- `_quarto-fr.yml` with an [announcement bar](https://quarto.org/docs/websites/website-tools.html#announcement-bar) in French; -- `_quarto-en.yml` with an [announcement bar](https://quarto.org/docs/websites/website-tools.html#announcement-bar) in English. - -You could use the same strategy for having different navbars in the different language versions of a multilingual website. - -This uses [Quarto profiles](https://quarto.org/docs/projects/profiles.html) under the hood. -You can still use other profiles such as development and production, by passing them as the `profile` argument of `render_book()` and `render_website()`. - -### Configure templates - -If you want, say, a banner with different content in the different languages, you can create a [partial template](https://quarto.org/docs/journals/templates.html#html-partials) and in it use the variables `lang-fr` and `lang-en` for instance for content in French and English. - -The Quarto configuration file `_quarto.yml` would include: - -```yaml -format: - html: - template-partials: - - metadata.html -``` - -The end of the `metadata.html` template would be: - -```html - -
-$if(lang-en)$Hello$endif$ -$if(lang-fr)$Salut$endif$ -$if(lang-es)$Hola$endif$ -
-``` - -## Content translation - -From a book whose main language is English... - -```{r} -parent_dir <- withr::local_tempdir() -project_dir <- "babelbook" -quarto_bin <- quarto::quarto_path() -withr::with_dir(parent_dir, { - sys::exec_wait( - quarto_bin, - args = c("create-project", project_dir, "--type", "book") - ) -}) -``` - -- Register languages in the Quarto configuration, for instance - -```{r} -project_path <- file.path(parent_dir, project_dir) -babelquarto::register_main_language(main_language = "en", project_path = project_path) -babelquarto::register_further_languages(further_languages = "es", project_path = project_path) -``` - - -This is how the config file now looks like: - -````{r, results='asis', echo=FALSE} -c( - "```yaml", - readLines(file.path(project_path, "_quarto.yml")), - "```" -) |> - paste(collapse = "\n") |> - cat() -```` - - -- qmd/Rmd files. `bla.qmd` translation in Spanish would live in `bla.es.qmd`. See [babeldown](https://docs.ropensci.org/babeldown) for getting an automated translation. -- parts. The part title translation can be stored in `_quarto.yml` like so: - -```yml - - part: Building Your Package - part-es: Construyendo tu paquete - chapters: - - pkg_building.Rmd - - pkg_ci.Rmd - - pkg_security.Rmd -``` - -If it does not exist, babelquarto falls back to the part title in the main language. - -- title, author, description. Their translation can be stored in `_quarto.yml` like so (NOT in the `book` list): - -```yml -book: - title: Cool book - author: Myself - -title-es: Libro genial -author-es: Yo misma -``` - -If these fields do not exist, babelquarto falls back to their text in the main language. - -Note that babelquarto does not _translate_ the content! -Translation tooling lives in [babeldown](https://docs.ropensci.org/babeldown). diff --git a/README.md b/README.md index 3a588bb..edefa0a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,4 @@ - - # babelquarto @@ -8,12 +6,15 @@ [![R-CMD-check](https://github.com/ropensci-review-tools/quartobabel/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci-review-tools/quartobabel/actions/workflows/R-CMD-check.yaml) -The goal of babelquarto is to render a Quarto multilingual project, book +The goal of {babelquarto} is to render a Quarto multilingual project, book or website. +Note that babelquarto does not *translate* the content! Translation +tooling lives in {[babeldown](https://docs.ropensci.org/babeldown)}. + ## Installation -You can install the development version of babelquarto from rOpenSci +You can install the development version of {babelquarto} from rOpenSci R-universe: ``` r @@ -27,315 +28,19 @@ Or from [GitHub](https://github.com/) with: pak::pak("ropensci-review-tools/babelquarto") ``` -Once using babelquarto, you cannot render your book or website using -Quarto CLI (or the RStudio IDE render button) directly. You need to use -`babelquarto::render_book()` or `babelquarto::render_website()`, -respectively. - -## Example book - -Create a starter/example book. - -``` r -parent_dir <- withr::local_tempdir() -project_dir <- "blop" -babelquarto::quarto_multilingual_book(parent_dir = parent_dir, project_dir = project_dir) -#> [1] "/var/folders/gd/rrsyq__147x_8y_3zcpymj_40000gn/T//Rtmpr3nsvT/filed2be237749e5/blop" -readLines(file.path(parent_dir, project_dir, "_quarto.yml")) -#> [1] "project:" " type: book" -#> [3] "" "book:" -#> [5] " site-url: https://example.com" " title: \"blop\"" -#> [7] " author: \"Pascal Burkhard\"" " date: \"11.09.2024\"" -#> [9] " chapters:" " - index.qmd" -#> [11] " - intro.qmd" " - summary.qmd" -#> [13] " - references.qmd" "" -#> [15] "bibliography: references.bib" "" -#> [17] "format:" " html:" -#> [19] " theme: cosmo" "" -#> [21] "babelquarto:" " languagelinks: sidebar" -#> [23] " languagecodes:" " - name: es" -#> [25] " text: \"Version in es\"" " - name: fr" -#> [27] " text: \"Version in fr\"" " - name: en" -#> [29] " text: \"Version in en\"" " mainlanguage: 'en'" -#> [31] " languages: ['es', 'fr']" "title-es: title in es" -#> [33] "title-fr: title in fr" "description-es: description in es" -#> [35] "description-fr: description in fr" "author-es: author in es" -#> [37] "author-fr: author in fr" "lang: en" -fs::dir_tree(file.path(parent_dir, project_dir)) -#> /var/folders/gd/rrsyq__147x_8y_3zcpymj_40000gn/T//Rtmpr3nsvT/filed2be237749e5/blop -#> ├── _quarto.yml -#> ├── cover.png -#> ├── index.es.qmd -#> ├── index.fr.qmd -#> ├── index.qmd -#> ├── intro.es.qmd -#> ├── intro.fr.qmd -#> ├── intro.qmd -#> ├── references.bib -#> ├── references.es.qmd -#> ├── references.fr.qmd -#> ├── references.qmd -#> ├── summary.es.qmd -#> ├── summary.fr.qmd -#> └── summary.qmd -``` - -``` r -babelquarto::render_book(file.path(parent_dir, project_dir)) -``` - -We end up with three books, that cross-link to each other from the left -sidebar. [Example](https://devdevguide.netlify.app). - -## Example website - -Create a starter/example website. - -``` r -parent_dir <- withr::local_tempdir() -project_dir <- "blop" -babelquarto::quarto_multilingual_website(parent_dir = parent_dir, project_dir = project_dir) -#> [1] "/var/folders/gd/rrsyq__147x_8y_3zcpymj_40000gn/T//Rtmpr3nsvT/filed2be4d2b3e3/blop" -readLines(file.path(parent_dir, project_dir, "_quarto.yml")) -#> [1] "project:" " type: website" -#> [3] "" "website:" -#> [5] " site-url: https://example.com" " title: \"blop\"" -#> [7] " navbar:" " left:" -#> [9] " - href: index.qmd" " text: Home" -#> [11] " - about.qmd" "" -#> [13] "format:" " html:" -#> [15] " theme: cosmo" " css: styles.css" -#> [17] " toc: true" "" -#> [19] "" "" -#> [21] "" "babelquarto:" -#> [23] " languagelinks: navbar" " languagecodes:" -#> [25] " - name: es" " text: \"Version in es\"" -#> [27] " - name: fr" " text: \"Version in fr\"" -#> [29] " - name: en" " text: \"Version in en\"" -#> [31] " mainlanguage: 'en'" " languages: ['es', 'fr']" -#> [33] "title-es: title in es" "title-fr: title in fr" -#> [35] "description-es: description in es" "description-fr: description in fr" -#> [37] "author-es: author in es" "author-fr: author in fr" -#> [39] "lang: en" -fs::dir_tree(file.path(parent_dir, project_dir)) -#> /var/folders/gd/rrsyq__147x_8y_3zcpymj_40000gn/T//Rtmpr3nsvT/filed2be4d2b3e3/blop -#> ├── _quarto.yml -#> ├── about.es.qmd -#> ├── about.fr.qmd -#> ├── about.qmd -#> ├── index.es.qmd -#> ├── index.fr.qmd -#> ├── index.qmd -#> └── styles.css -``` - -``` r -babelquarto::render_website(file.path(parent_dir, project_dir)) -``` - -[Example](https://maelle.github.io/babelsite), -[source](https://github.com/maelle/babelsite) - -## Configure the base URL - -Use the [usual Quarto -field](https://quarto.org/docs/websites/website-tools.html), or use the -`site_url` argument of `babelquarto::render_book()`. - - book: - site-url: https://example.com - -## Configure the version text - -If you want the choice to be between, say “English” and “Español” rather -than “Version in EN” and “Version in ES”, add these fields under the -babelquarto YAML key, in `_quarto.yml`: - -``` yaml -babelquarto: - languagecodes: - - name: es - text: "Español" - - name: en - text: "English" -``` - -Using `babelquarto::register_main_language()` and -`babelquarto::register_further_languages()` will create the -boilertemplate for these fields. - -## Configure the language link placement - -The language link menu can be placed in the *sidebar* or in the -*navbar*. To change the placement, use the `languagelinks` field in the -babelquarto YAML key, in `_quarto.yml`: - -``` yaml -babelquarto: - languagelinks: sidebar -``` - -Beware: depending on the value of `languagelinks`, the corresponding -menu needs to be configured. Books always have a *sidebar*, but websites -can have either *navbar* or *sidebar*. See [Quarto -documentation](https://quarto.org/docs/websites/website-navigation.html#side-navigation) -for more information. - -## Distinct configuration per language - -There are two complementary/overlapping solutions for making the -different language versions distinct (different banner, different navbar -for instance): - -### Configuration file per language +## Getting Started -For a book with French (“fr”) and English (“en”) versions you could have -three Quarto configuration files: +The {babelquarto} package allows you to create and render a multilingual Quarto project, book or website. +A multilingual project is based on a main language and can feature any number of additional languages. +The languages are registered once and are then present in your `_quarto.yml` configuration file under the `babelquarto` key. +Each Quarto Markdown file in your project can then be translated into these further languages and these will be used to generate the project in each language. -- `_quarto.yml` with the general configuration including the chapters - list; -- `_quarto-fr.yml` with an [announcement - bar](https://quarto.org/docs/websites/website-tools.html#announcement-bar) - in French; -- `_quarto-en.yml` with an [announcement - bar](https://quarto.org/docs/websites/website-tools.html#announcement-bar) - in English. +If you start from scratch, you might want to look at `babelquarto::quarto_multilingual_book()` or `babelquarto::quarto_multilingual_website()` and read `vignette("babelquarto")`. -You could use the same strategy for having different navbars in the -different language versions of a multilingual website. +If you already have and existing Quarto project and want to convert it to a multilingual project, you can use `babelquarto::register_main_language()` and `babelquarto::register_further_languages()` to get started. For more information you can read `vignette("convert)`. -This uses [Quarto -profiles](https://quarto.org/docs/projects/profiles.html) under the -hood. You can still use other profiles such as development and -production, by passing them as the `profile` argument of `render_book()` -and `render_website()`. +## Examples -### Configure templates +To get a feel of what a multilingual book can look like, you can have a look at this book: [*rOpenSci Packages: Development, Maintenance, and Peer Review*](https://devguide.ropensci.org/). -If you want, say, a banner with different content in the different -languages, you can create a [partial -template](https://quarto.org/docs/journals/templates.html#html-partials) -and in it use the variables `lang-fr` and `lang-en` for instance for -content in French and English. - -The Quarto configuration file `_quarto.yml` would include: - -``` yaml -format: - html: - template-partials: - - metadata.html -``` - -The end of the `metadata.html` template would be: - -``` html - -
-$if(lang-en)$Hello$endif$ -$if(lang-fr)$Salut$endif$ -$if(lang-es)$Hola$endif$ -
-``` - -## Content translation - -From a book whose main language is English… - -``` r -parent_dir <- withr::local_tempdir() -project_dir <- "babelbook" -quarto_bin <- quarto::quarto_path() -withr::with_dir(parent_dir, { - sys::exec_wait( - quarto_bin, - args = c("create-project", project_dir, "--type", "book") - ) -}) -#> [1] 0 -``` - -- Register languages in the Quarto configuration, for instance - -``` r -project_path <- file.path(parent_dir, project_dir) -babelquarto::register_main_language(main_language = "en", project_path = project_path) -babelquarto::register_further_languages(further_languages = "es", project_path = project_path) -``` - -This is how the config file now looks like: - -``` yaml -project: - type: book - -book: - title: "babelbook" - author: "Norah Jones" - date: "11.09.2024" - chapters: - - index.qmd - - intro.qmd - - summary.qmd - - references.qmd - -bibliography: references.bib - -format: - html: - theme: cosmo - pdf: - documentclass: scrreprt - - - - -babelquarto: - languagecodes: - - name: es - text: "Version in es" - - name: en - text: "Version in en" - mainlanguage: 'en' - languages: ['es'] -title-es: title in es -description-es: description in es -author-es: author in es -lang: en -``` - -- qmd/Rmd files. `bla.qmd` translation in Spanish would live in - `bla.es.qmd`. See [babeldown](https://docs.ropensci.org/babeldown) for - getting an automated translation. -- parts. The part title translation can be stored in `_quarto.yml` like - so: - -``` yml - - part: Building Your Package - part-es: Construyendo tu paquete - chapters: - - pkg_building.Rmd - - pkg_ci.Rmd - - pkg_security.Rmd -``` - -If it does not exist, babelquarto falls back to the part title in the -main language. - -- title, author, description. Their translation can be stored in - `_quarto.yml` like so (NOT in the `book` list): - -``` yml -book: - title: Cool book - author: Myself - -title-es: Libro genial -author-es: Yo misma -``` - -If these fields do not exist, babelquarto falls back to their text in -the main language. - -Note that babelquarto does not *translate* the content! Translation -tooling lives in [babeldown](https://docs.ropensci.org/babeldown). +For a multilingual website, you can check out [Joel Nitta's website](https://www.joelnitta.com/). diff --git a/_pkdown.yml b/_pkdown.yml new file mode 100644 index 0000000..ec0a740 --- /dev/null +++ b/_pkdown.yml @@ -0,0 +1,2 @@ +template: + bootstrap: 5 diff --git a/man/figures/logo.png b/man/figures/logo.png new file mode 100644 index 0000000..de60c8d Binary files /dev/null and b/man/figures/logo.png differ diff --git a/vignettes/.gitignore b/vignettes/.gitignore new file mode 100644 index 0000000..075b254 --- /dev/null +++ b/vignettes/.gitignore @@ -0,0 +1 @@ +/.quarto/ diff --git a/vignettes/babelquarto.qmd b/vignettes/babelquarto.qmd new file mode 100644 index 0000000..da6ae68 --- /dev/null +++ b/vignettes/babelquarto.qmd @@ -0,0 +1,165 @@ +--- +title: "Get started" +vignette: > + %\VignetteIndexEntry{Get started} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + +The goal of this vignette is to show how you can start and maintain a new multilingual Quarto project using {babelquarto}. +There are two types of projects: a book or a website. We will look at each type separately below. + +If you want to turn an existing project into a multilingual project, have a look at `vignette("convert")`. + +## Installing babelquarto + +Before you can start a new multilingual project, you need to install {babelquarto}. + +```r +install.packages('babelquarto', repos = c('https://ropensci.r-universe.dev', 'https://cloud.r-project.org')) +``` + +Or from [GitHub](https://github.com/) with: + +``` r +# install.packages("pak") +pak::pak("ropensci-review-tools/babelquarto") +``` + +## Starting a multilingual book + +To start a multilingual book, use `quarto_multilingual_book()` with the `parent_dir` argument to specify where you want to create the project and the `project_dir` argument to specify the name of the project. +The argument `main_language` is used to specify the main language of the project and `further_languages` lists all additional languages. + +```{r} +#| label: setup_book +#| results: 'hide' +parent_dir <- withr::local_tempdir() +project_dir <- "multilingual_book" +babelquarto::quarto_multilingual_book( + parent_dir = parent_dir, + project_dir = project_dir, + main_language = "en", + further_languages = c("es", "fr") +) +``` + +Look at the `_quarto.yml` file in the project directory. +To get familiar with the configuration, take a look at the example below: + +```{r} +#| label: display_book_config +#| echo: false +#| results: 'asis' + +cat("```yaml\n") +readLines(file.path(parent_dir, project_dir, "_quarto.yml")) |> + cat(sep = "\n") +cat("```\n") +``` + +The file structure of the project looks like this: + +```{r} +#| label: book_dir_structure +fs::dir_tree(file.path(parent_dir, project_dir)) +``` + +Each Quarto file has a Spanish and a French version. +These files aren't automatically translated and are just copies of the original English version. +You will have to provide the translations yourself, or look at {[babeldown](https://docs.ropensci.org/babeldown/)} for automatic translation. +If you look at the `index.qmd` file, you'll see that the French file is called `index.fr.qmd` and the Spanish file is called `index.es.qmd`. + +When you're ready to render your book, use `render_book()`: + +```{r} +#| label: render_book +#| eval: false +babelquarto::render_book(file.path(parent_dir, project_dir)) +``` + +We end up with three books, that cross-link to each other from the left sidebar. +[Example](https://devguide.ropensci.org/). + +## Starting a multilingual website + +To start a multilingual website, use `quarto_multilingual_website()` with the `parent_dir` argument to specify where you want to create the project and the `project_dir` argument to specify the name of the project. +The argument `main_language` is used to specify the main language of the project and `further_languages` lists all additional languages. + +```{r} +#| label: setup_website +#| results: 'hide' +parent_dir <- withr::local_tempdir() +project_dir <- "multilingual_website" +babelquarto::quarto_multilingual_website( + parent_dir = parent_dir, + project_dir = project_dir, + main_language = "en", + further_languages = c("es", "fr") +) +``` + +Look at the `_quarto.yml` file in the project directory. To get familiar with the configuration, take a look at the example below: + +```{r} +#| label: display_website_config +#| echo: false +#| results: 'asis' + +cat("```yaml\n") +readLines(file.path(parent_dir, project_dir, "_quarto.yml")) |> + cat(sep = "\n") +cat("```\n") +``` + +The file structure of the project looks like this: + +```{r} +#| label: website_dir_structure +fs::dir_tree(file.path(parent_dir, project_dir)) +``` + +Each Quarto file has a Spanish and a French version. +These files aren't automatically translated and are just copies of the original English version. +You will have to provide the translations yourself, or look at {[babeldown](https://docs.ropensci.org/babeldown/)} for automatic translation. +If you look at the `index.qmd` file, you'll see that the French file is called `index.fr.qmd` and the Spanish file is called `index.es.qmd`. + +When you're ready to render your website, use `babelquarto::render_website()`: + +```{r} +#| label: render_website +#| eval: false +babelquarto::render_website(file.path(parent_dir, project_dir)) +``` + +We end up with a multilingual website. [Example](https://maelle.github.io/babelsite), [source](https://github.com/maelle/babelsite) + +## Previewing your multilingual project + +Once you have rendered your project, you will have a `_site` or `_book` folder in your project. +In Quarto you would use `quarto preview` to be able to get a look at what you project looks like. +Because of the way {babelquarto} operates, this isn't possible. +You can however preview your files using the [{servr} package](https://cran.rstudio.com/web/packages/servr/index.html). + +You can use `servr::httw()` to preview your project. + +```{r} +#| eval: false +# For a multilingual website +servr::httw("_site") + +# For a multilingual book +servr::httw("_book") +``` + +This will show an URL that you can open in your IDE or browser to see your project. + +## Next steps + +Take a deeper dive into the configuration options available in {babelquarto} you can have a look at `vignette("configuration")`. + +If you want to translate your multilingual project using automatic translation with DeepL, you should have a look at [babeldown](http://docs.ropensci.org/babeldown/articles/quarto.html). + +If you want to setup your own CI and deploy your website, have a look at `vignette("render-with-ci")`. + +If you need to personalize the Quarto templates, have a look at `vignette("custom-templates")`. diff --git a/vignettes/configuration.qmd b/vignettes/configuration.qmd new file mode 100644 index 0000000..3a7e735 --- /dev/null +++ b/vignettes/configuration.qmd @@ -0,0 +1,139 @@ +--- +title: "Configuration" +vignette: > + %\VignetteIndexEntry{Configuration} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + +The goal of this vignette is to show the configuration options that are available in {babelquarto}. + +## Basic configuration + +When you start a {babelquarto} project, from scratch or from an existing project, your `_quarto.yml` file will contain a number of new options: + +```{r} +#| echo: false +#| message: false +#| results: 'asis' +parent_dir <- withr::local_tempdir() +project_dir <- "multilingual_book" +book <- babelquarto::quarto_multilingual_book( + parent_dir = parent_dir, + project_dir = project_dir +) +config_path <- file.path(parent_dir, project_dir, "_quarto.yml") +config_lines <- brio::read_lines(config_path) +where_babelquarto <- grep("babelquarto:", config_lines, fixed = TRUE) + +cat("```yaml\n") +config_lines[where_babelquarto:length(config_lines)] |> + cat(sep = "\n") +cat("```\n") +``` + +By default, {babelquarto} will have the following options under the `babelquarto` key: + +| | | +|------------------------------------|------------------------------------| +| `languagelinks` | Where the menu with the links to other languages will be placed. Can be either `sidebar` or `navbar`. | +| `languagecodes` | A list with each language defined. Each entry has a `name` with the language abbreviation (for example *en* or *es*. The `text` key changes the text used for the links to this language. | +| `mainlanguage` | The main language of the project. | +| `languages` | An array of the additional languages (not including the main language). | + +In addition to the `babelquarto` key, you will see language specific keys for `title`, `description` and `author`. These keys allow you to have a specific title, description or author in for each additional language. + +### Customizing the language menu labels + +If you want the choice to be between, say "English" and "Español" rather than "Version in EN" and "Version in ES", add these fields under the `babelquarto/languagecodes` key, in `_quarto.yml`: + +```yaml +babelquarto: + languagecodes: + - name: es + text: "Español" + - name: en + text: "English" +``` + +Using `register_main_language()` and `register_further_languages()` will create the boilertemplate for these fields. + +## Configure the base URL + +If you need to configure a base URL, you can use the [usual Quarto field](https://quarto.org/docs/websites/website-tools.html), or use the `site_url` argument of `render_book()`. + +```yaml +book: + site-url: https://example.com +``` + +```yaml +website: + site-url: https://example.com +``` + +If you render your multilingual book or website in a CI context, you need will need to set the `BABELQUARTO_CI_URL` environment variable. See `vignette("render-with-ci")` for more information. + +## Translate parts in multilingual books + +In multilingual books, if you use parts to structure your book, you can translate the part titles like so: + + +```yaml +book: + chapters: + - index.qmd + - part: Foreword + part-fr: Préface + chapters: + - foreword.qmd + - part: Explore + part-fr: Explorer + chapters: + - intro-explore.qmd + - data-visualisation.qmd +``` + +For each additional language, you can use a `part-xx` key to translate the part title. + +## Using profiles for advanced configuration + +For more advanced customization, you can use [Quarto project profiles](https://quarto.org/docs/projects/profiles.html). +In {babelquarto} we will automatically load a language profile if it exists in the project directory and follows our naming convention. +Profile configuration are **merged** with the main `_quarto.yml` file. + +For example, let's say you have a project with English as the main language and French as an additional language. +When rendering the main English language, {babelquarto} will load the *en* profile and the *fr* profile when rendering the French version. + +You could for example have different navigation menus for each language: + +```{.yaml filename="_quarto-en.yml"} +website: + navbar: + title: "My Website" + left: + - label: "Home" + href: "index.qmd" + right: + - label: "About" + href: "about.qmd" +``` + +```yaml +website: + navbar: + title: "Mon site web" + left: + - label: "Accueil" + href: "index.qmd" + right: + - label: "À propos" + href: "about.qmd" +``` + +Profiles allow for advanced configuration, but a careful read of the [profiles documentation](https://quarto.org/docs/projects/profiles.html) is recommended. +The main `_quarto.yml` file will be merged with the profile options and this often needs a careful planning of what keys are put in the different configuration files. + +### Additional profiles + +For complex project, you might want to use additional profiles. When you render a project, you can pass a `profile` argument to `render_book()` and `render_website()` to use additional profiles. The profile will be merged with the main `_quarto.yml` and the language profile. diff --git a/vignettes/convert.qmd b/vignettes/convert.qmd new file mode 100644 index 0000000..423958e --- /dev/null +++ b/vignettes/convert.qmd @@ -0,0 +1,71 @@ +--- +title: "Convert an existing project" +description: > + How to convert an existing project to a multilingual Quarto project +vignette: > + %\VignetteIndexEntry{Convert an existing project} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + +If you want to turn an existing project into a multilingual project, you can use {babelquarto}'s `register_main_language()` and `register_further_languages()` functions. + +Let's start with a book whose main language is English. + +```{r} +#| results: 'hide' +parent_dir <- withr::local_tempdir() +project_dir <- "babelbook" +quarto_bin <- quarto::quarto_path() +withr::with_dir(parent_dir, { + sys::exec_wait( + quarto_bin, + args = c("create-project", project_dir, "--type", "book") + ) +}) +``` + +First you'll need to register the main language in the Quarto configuration: + +```{r} +project_path <- file.path(parent_dir, project_dir) +babelquarto::register_main_language( + main_language = "en", + project_path = project_path +) +``` + +Then you can add further languages, say Spanish and French: + +```{r} +babelquarto::register_further_languages( + further_languages = c("es", "fr"), + project_path = project_path +) +``` + +We end up with a multilingual book in English and Spanish. If you look at the `_quarto.yml` file in the project directory, you'll see that the `main_language` key is `en` and the `languages` key contains `es` and `fr`. + +```{r} +#| echo: false +#| results: 'asis' + +cat("```yaml\n") +readLines(file.path(parent_dir, project_dir, "_quarto.yml")) |> + cat(sep = "\n") +cat("```\n") +``` + +You can now start translating your book into Spanish and French. Each file of you project can be translated by adding a suffix to the file name. +For example, the Spanish version of `index.md` will be in `index.es.md` and the French version in `index.fr.md`. + +You will have to provide the translations yourself. +If you want to translate your multilingual project using automatic translation with DeepL, you should have a look at [babeldown](http://docs.ropensci.org/babeldown/articles/quarto.html). + +## Next steps + +Take a deeper dive into the configuration options available in {babelquarto} you can have a look at `vignette("configuration")`. + +If you want to deploy your website on continuous integration, have a look at `vignette("render-with-ci")`. + +If you need to personalize the quarto templates, have a look at `vignette("custom-templates")`. diff --git a/vignettes/custom-templates.qmd b/vignettes/custom-templates.qmd new file mode 100644 index 0000000..82e5f39 --- /dev/null +++ b/vignettes/custom-templates.qmd @@ -0,0 +1,45 @@ +--- +title: "Custom templates" +description: > + How to have multilingual parts in your custom templates +vignette: > + %\VignetteIndexEntry{Convert an existing project} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + +The goal of this vignette is to show how you can have multilingual parts in your custom templates. + +If you need a more advanced way of customizing you project, you can use [Quarto's custom templates](https://quarto.org/docs/journals/templates.html). +This allows you to have a more fine-grained control over the render of your pages. + +In order to use the multilingual features of {babelquarto} in your custom templates, we provide a variable for each language rendered in the project. +The variable is named `lang-en` for an English render, `lang-fr` for a French render and so on. +This allows you to have different content for each language in your custom templates. +You can use [pandoc's `$if(lang-en)$` syntax](https://pandoc.org/MANUAL.html#conditionals) to conditionally include content based on the language. + +## Example + +If you want to have a specific metadata block on your webpage, you might want to use the [`medadata.html` partial from Quarto](https://quarto.org/docs/journals/templates.html#html-partials). + +You would configure your `_quarto.yml` file like this: + +``` yaml +format: + html: + template-partials: + - metadata.html +``` + +In your `metadata.html` file, you can use the `lang-en` variable to have a specific metadata block for the English render and the `lang-fr` variable for the French render. The end of the metadata.html template would be: + +``` html + +$if(lang-en)$ + +$endif$ +$if(lang-fr)$ + +$endif$ + +``` diff --git a/vignettes/render-with-ci.qmd b/vignettes/render-with-ci.qmd new file mode 100644 index 0000000..cf367bc --- /dev/null +++ b/vignettes/render-with-ci.qmd @@ -0,0 +1,33 @@ +--- +title: "Render with continuous integration (CI)" +description: > + How to render with continuous integration +vignette: > + %\VignetteIndexEntry{Render with CI} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +--- + +If you want to render and publish your multilingual book or website with CI, you must render your project with `render_book()` or `render_website()`, respectively. +Don't use Quarto's own render and publish steps. +You can find more information about publishing with CI in the [Quarto documentation](https://quarto.org/docs/publishing/ci.html). + +### Site URL + +When you render a project in a CI context, you need to set the URL of the publishing website in an environement variable. +You can do that with the `BABELQUARTO_CI_URL` environment variable. + +### Steps for rendering + +To render your project with CI, you need to follow these general steps: + +* Install the necessary dependencies including Quarto and R dependencies +* Render you project using {babelquarto}'s `render_book()` or `render_website()` functions +* Publish the rendered HTML (_site or _book folder) where you deploy your project (a GitHub pages branch, Netlify, etc.) + +## Example + +Here are two examplee of how you could render a multilingual book with CI using GitHub Actions: + +* A demo [Babelbook](https://nenuial.github.io/babelbook/) with its [workflow file](https://github.com/Nenuial/babelbook/blob/main/.github/workflows/publish.yml) +* The [rOpenSci Packages: Development, Maintenance, and Peer Review](https://devguide.ropensci.org/index.html) book with its [workflow file](https://github.com/ropensci/dev_guide/blob/main/.github/workflows/scheduled-manual-main.yml)