i18n support - Githubissues

jplecavalier commented 3 years ago

Would it be possible to integrate a standard way to translate keywords for sites created with pkgdown? Adding a i18n section in the _pkgdown.yml file could be an easy way to implement it on the front end.

I'm thinking of something like :

i18n:
  # keyword: "Translated term"
  # e.g.
  unreleased_version: "Version inédite"
  get_started: "Introduction"
  reference: "Références"
  # and-so-on...

I know I could easily fix some by customizing the navbar or the version_tooltip parameter for example, but I still think that a specific node in the YAML used explicitly to translate terms could be nice.

Any thoughts on that?

cjvanlissa commented 3 years ago

Seconded

hadley commented 3 years ago

From initial look at rendered site, places where hard coded English content currently appears:

navbar (get started, reference, articles, news, search, etc) + version tooltip
sidebar on homepage (links, link text, license, license text, community, developers, developer roles)
sidebar on other pages (contents)
footer (developed by, built with)
articles (source)
reference (arguments, examples) (generated in as_data and friends)
news (CRAN release)

Need to inspect source for more:

The headers of most pages are hard coded in the template
Some text for screen readers (skip link + toggle navigation in navbar)
The language inserted in the <html> tag
Fallback 404 page

All in all, this is much less than I had expected, so internationalisation seems reasonable feasible. The main decisions are how to encode the data in the yaml: do we want (e.g.) navbar.i18n or i18n.navbar? And should pkgdown bundle translations for some languages? If so, which ones should we start with and what's the policy for adding new languages and keeping them up to date?

jplecavalier commented 3 years ago

I think the way Hugo wowchemy (former academic) theme manage the i18n keywords is elegant. We could include language bundles directly into the package and give the user the possibility to define a custom language in the config file.

The bundled languages could be defined here:

inst/i18n/_template.yml
inst/i18n/en.yml
inst/i18n/fr.yml
etc.

Then the user could select one of those bundled languages in _pkgdown.yml (default to en):

[...]

i18n:
  lang: fr

[...]

The user could also make some custom changes in a defined language (or use that feature to implement a language not included with the package as of now):

[...]

i18n:
  lang: fr
  custom:
    unreleased_version: "Version inédite"
    get_started: "Introduction"
    reference: "Références"

[...]

Any keyword not defined in i18n:custom will fallback on the template i18n:lang.

We could ask contributors to fill in inst/i18n/_template.yml and open a PR if they want to add any specific language bundle.

I could easily make a PR for inst/i18n/_template.yml (I will search through the source to identify every hardcoded words), inst/i18n/en.yml and inst/i18n/fr.yml, but I'm not sure I would get it right to adjust all the source code to be fed with those files effectively.

Let me know if you need any help on that, it would be a pleasure.

maelle commented 3 years ago

Linking the similar issue for bs4_book https://github.com/rstudio/bookdown/issues/1245

hadley commented 3 years ago

I think I will probably use R's standard translation system for this (i.e. .po files). It's a bit of a stretch, and it means it won't be easy to provide translations outside of pkgdown, but I think the benefits of forcing me to work within this system will outweigh the downsides.

hadley commented 3 years ago

[x] navbar (get started, reference, articles, news, search, etc)
[x] version tooltip
[x] sidebar on homepage (links, link text, license, license text, community, developers, developer roles)
[x] sidebar on other pages (contents)
[x] footer (developed by, built with)
[x] articles (source)
[x] reference (arguments, examples) (generated in as_data and friends)
[x] news (CRAN release)
[x] page titles
[x] screen readers (skip link + toggle navigation in navbar)
[x] fallback 404 page
[x] lang attribute on <html>

hadley commented 3 years ago

@cjvanlissa would you be interested in contributing a translation? If so, let me know which language, and I can sketch out the process. (It's a little tricky right now, but I'm working on contributing improvements to various packages so that it gets easier in the future).

bendeivide commented 7 months ago

@hadley, if you are interested, I can translate it into Portuguese (pt_BR). It will be a pleasure to participate in this contribution!

maelle commented 7 months ago

:wave: @bendeivide! I'm taking the liberty to be the one answering. :wink: Fantastic, thank you! I think the most up to date guidance is https://github.com/r-lib/pkgdown/issues/1985#issuecomment-1004274955 except that potools is on CRAN now so you can simply run install.packages("potools"). Happy to help if you run into any problem.

Side-note: In general I'd recommend opening a new issue rather than commenting on an old one.

bendeivide commented 7 months ago

Thank you!

r-lib / pkgdown

i18n support #1446