rstudio / bookdown

Authoring Books and Technical Documents with R Markdown
https://pkgs.rstudio.com/bookdown/
GNU General Public License v3.0
3.78k stars 1.27k forks source link

[FR] Add internationalization options for the bs4_book.html template #1245

Open emilopezcano opened 3 years ago

emilopezcano commented 3 years ago

Description of the problem

Even though a number of things can be configured for other languages, as described in Sect. 4.5 of the Bookdown book, I have not found a way to change other things in the bs4_book() output (see screen capture). I search for an Issue in the report and in Stackoverflow with no success.

Workaround

I edited (hard-code) the template locally (<.libPaths()>/bookdown/templates/bs4_book.html), changing the hard-coded English sentences by the Spanish ones I wanted (see attachment in txt). That works for me, but I don't know if a package update will overwrite the template or otherwise I will probably miss improvements in the template. I edited the following lines:

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L64

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L68

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L72

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L93

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L98

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L99

Proposed solution

Maybe the template could include parameterised values for the specific bs4_book ui elements, as it does for example with the author or title. And this could be set in the language/ui sections of _bookdown.yml (or other suitable place).

Thank you for all the work

Captura de pantalla 2021-08-31 a las 17 36 30

bs4_book_es.html.txt

emilopezcano commented 3 years ago

Another possible solution, simpler than the $variables$ approach:

  1. Provide translated templates as bs4_book_XX.html (I could translate the Spanish one)
  2. Allow an option for the language
  3. Use the template given the option

The default option could be either the English one or the one in the LOCALE.

NOTE: In addition to the lines reported above, the ones for the footer should be also translated:

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L112

https://github.com/rstudio/bookdown/blob/23798df80f9ade52836f76c31ea701c576d707a2/inst/templates/bs4_book.html#L116

cderv commented 3 years ago

Provide translated templates as bs4_book_XX.html (I could translate the Spanish one)

About this, I have just merged a PR (#1247) to be able to provide a custom template based on the default one. This could be one usage.

In any case, these are nice option. We are not working currently closely on bookdown but you are right reminding us of the internationalization issue. We need to do something about this.

Best thing would be to stay close to how it work for gitbook(), but I like the idea of translated template, which could be easily included and configurable using the new user facing template argument ("default", "default-es"). Only drawback with this kind of thing is the maintainance - it requires to maintain several files with the same content.

A mechanism for easier configuration by any user to modified the default template using variables would be better. (Either pandoc variable, or any other templating system, using English as default)

We'll think of something next time we'll work closely on bookdown new features

emilopezcano commented 3 years ago

That's great, thank you Christophe.

Just in case it is useful: for the internationalisation of my Shiny Apps, I use the shiny.i18 package. I don't know if there is something more general (not just for shiny). The good thing would be that you do not need to maintain several templates, but just a file with the translations of the words or sentences. If a translation is missed, the default text (e.g., English) is shown. A very small side effect versus other errors when maintaining many files 😊

For now, the template solution is fine for me. Thank you very much!

cderv commented 3 years ago

I don't know how this package works for shiny. And I don't know if there is something similar for R Markdown output formats. However, I'll keep that in mind when working on it.

I agree that an external configuration file for translation of words or sentence would be better than maintaining by end several templates.

tamas-ferenci commented 1 week ago

Dear @cderv , I was wondering if there are any updates on this. Modifying the template and using a custom template is a possible solution, but it would mean that every update on the main template file should be manually followed with the translation.

cderv commented 3 days ago

Unfortunately, I am not actively working on bookdown right now. Especially as focus is on Quarto, which the Book format has some already internationalization option (https://quarto.org/docs/authoring/language.html). The Quarto book format is based on boostrap like bs4_book(), but using Bootstrap 5.

Modifying the template and using a custom template is a possible solution, but it would mean that every update on the main template file should be manually followed with the translation.

This is true, though I don't think bs4_book() template will have modification in the feature, except for bug fixes IMO.

Though, @yihui and I will be more than happy to review a PR for this. Extending the existing feature at https://bookdown.org/yihui/bookdown/internationalization.html shouldn't be that hard. How I see things:

If anyone wants to give it a try, please do.

Otherwise, this good get done in the future when @yihui or I find time to add this feature. Currently time is a rare ressource considering number of projects around unfortunately, and priority is not on bookdown at the moment. Hope you'll understand.

Thank you !

tamas-ferenci commented 3 days ago

Thank you very much for a so detailed answer! I was also thinking of switching to quarto, but -- if I am not mistaken -- the exact same question will arise with quarto too... but correct me, if I'm wrong.

yihui commented 3 days ago

You can use JavaScript to modify the page arbitrarily, although it's less ideal than the metadata approach mentioned above. For example, you can change "View source" via:

document.getElementById('book-source').childNodes[0].textContent = 'View Rmd';
cderv commented 3 days ago

but -- if I am not mistaken -- the exact same question will arise with quarto too... but correct me, if I'm wrong.

Internationalization feature is more advanced there, and any hardcoded content is already translated in various languages. See the details at https://quarto.org/docs/authoring/language.html