Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

i18n support #1446

Closed
jplecavalier opened this issue Nov 19, 2020 · 10 comments · Fixed by #1861
Closed

i18n support #1446

jplecavalier opened this issue Nov 19, 2020 · 10 comments · Fixed by #1861

Comments

@jplecavalier
Copy link
Contributor

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
Copy link

Seconded

@hadley hadley changed the title Feature Request: Add i18n integration with pkgdown i18n support Oct 6, 2021
@hadley
Copy link
Member

hadley commented Oct 18, 2021 •
edited
Loading

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
Copy link
Contributor Author

jplecavalier commented Oct 19, 2021 •
edited
Loading

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
Copy link
Collaborator

maelle commented Oct 21, 2021

Linking the similar issue for bs4_book rstudio/bookdown#1245

@zkamvar zkamvar mentioned this issue Oct 21, 2021
Closed
@hadley
Copy link
Member

hadley commented Oct 27, 2021

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
Copy link
Member

hadley commented Oct 27, 2021 •
edited
Loading

  • 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)
  • page titles
  • screen readers (skip link + toggle navigation in navbar)
  • fallback 404 page
  • lang attribute on <html>

@hadley hadley mentioned this issue Oct 28, 2021
Merged
@zkamvar zkamvar mentioned this issue Oct 28, 2021
Closed
@hadley
Copy link
Member

hadley commented Nov 1, 2021

@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
Copy link

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

@maelle
Copy link
Collaborator

maelle commented Mar 19, 2024

👋 @bendeivide! I'm taking the liberty to be the one answering. 😉 Fantastic, thank you! I think the most up to date guidance is #1985 (comment) 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
Copy link

Thank you!

@hadley hadley mentioned this issue May 30, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Support translations r-lib/pkgdown
5 participants
@hadley @maelle @cjvanlissa @bendeivide @jplecavalier