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

Improve multilingual documentation/messages (addition of Spanish) #87

Open
Robinlovelace opened this issue Sep 7, 2024 · 15 comments
Open

Improve multilingual documentation/messages (addition of Spanish) #87

Robinlovelace opened this issue Sep 7, 2024 · 15 comments
Labels
enhancement New feature or request help wanted Extra attention is needed
Milestone
bilingual package

Comments

@Robinlovelace
Copy link
Collaborator

Above the current level (close to 0). Not sure how best to do this and seems it's early days in this space so just putting this out as a thought. Best up-to-date documentation I could find on this: https://ropensci.org/blog/2024/07/09/multilingual-documentation-wg/
@Robinlovelace Robinlovelace changed the title Improve multilingual documentation/messages Improve multilingual documentation/messages (addition of Spanish) Sep 7, 2024
@e-kotov
Copy link
Member

e-kotov commented Sep 7, 2024

I absolutely agree. I saw that post a few months ago. But I have to admit, I did not get back to it as we were progressing. Hopefully I have not accidentally made some design decision that will make it harder to do multilingual.

One thing that definitely makes easy adding language support, is the SQL bits, where I can just change the variable names. Also, as the original data codebooks are in Spanish... We are not so much at level 0 )

@Robinlovelace Robinlovelace added the help wanted Extra attention is needed label Sep 7, 2024
@llrs
Copy link
Member

llrs commented Sep 8, 2024

AFAIK, while that is still in progress and not yet merged with R, so users would need to install additional packages to make it work.

It will be easier to translate the error messages that enough would help users.
There is more experience in data.table via potools or with tools like Poedit (locally) or Weblate (server).

If you want to go towards translating the documentation you would need to define Language: on DESCRIPTION:

A ‘Language’ field can be used to indicate if the package documentation is not in English: this should be a comma-separated list of standard (not private use or grandfathered) IETF language tags as currently defined by RFC 5646 (https://www.rfc-editor.org/rfc/rfc5646, see also https://en.wikipedia.org/wiki/IETF_language_tag), i.e., use language subtags which in essence are 2-letter ISO 639-1 (https://en.wikipedia.org/wiki/ISO_639-1) or 3-letter ISO 639-3 (https://en.wikipedia.org/wiki/ISO_639-3) language codes.

Today I checked that and not that many packages respect (Many packages do not follow the ISO codes and use en-GB or similar codes).

@Robinlovelace
Copy link
Collaborator Author

Robinlovelace commented Sep 8, 2024 •
edited
Loading

Thanks @llrs I recall seeing potools and it seems like a lightweight and logical place to start for translating messages. Even lighter-weight would be to have a README-es.qmd file, if that works well -es versions of other vignettes could be worked on. In terms of order, possibly a README.es as a starter for 10 and then start on potools-aided translation templates, then we can invite translators from the community?

All of this relates to the fact that the package is in its infancy:

spanishoddata/README.qmd

Line 18 in 36f133b

[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-red.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental){target="_blank"}

I actually think it's more like maturing now but may have a rapid rate of evolution until it's been peer reviewed (we're planning a paper on the package) and submitted to CRAN. Experience with the https://github.com/geocompx/geocompr-es project suggests it's worth waiting until things stabilise before properly getting cranking on translations, so to speak. In the meantime, any thoughts on quick-and-simple README-es.qmd translation that should not be too much of a maintenance burden?

@llrs
Copy link
Member

llrs commented Sep 8, 2024

If you want to translate qmd vignettes the best approach might be to use babelquarto. Maëlle gave a talk last year at the Spanish conference about it 😄

I didn't know qmd were already supported at CRAN. Thanks!

@Robinlovelace
Copy link
Collaborator Author

The thing is, babelquarto is for quarto projects not R pkgs, right?

@llrs
Copy link
Member

llrs commented Sep 9, 2024

It says it is for websites too, I thought it would work for vignettes to.
@maelle Would babelquarto work for packages' vignettes or READMEs? I couldn't found a specific mention but as a website I thought it could work.

@maelle
Copy link

maelle commented Sep 9, 2024

Also tagging @yabellini as she has a lot of experience of multilingual projects.

babeldown, not babelquarto, can help translating vignettes. (I regret using such close names as it's really confusing). Now the problem is that there's no infrastructure to use the vignettes in different languages on a pkgdown website. The igraph package has one vignette in Spanish (under Get started) https://r.igraph.org/ but its metadata is wrong <html lang="en">. See r-lib/pkgdown#2258

@maelle
Copy link

maelle commented Sep 9, 2024

I wrote a short demo of potools to prepare for the talk Lluís mentioned: https://masalmon.eu/2023/10/06/potools-mwe/

@maelle
Copy link

maelle commented Sep 9, 2024

@Robinlovelace in the rOpenSci slack there's a channel called "multilingual" that would be relevant for your interests.

@maelle
Copy link

maelle commented Sep 9, 2024

Last comment for today! See https://github.com/ropensci/software-review/ for an example of a repo with a Spanish README linked from the main README.

@Robinlovelace
Copy link
Collaborator Author

Awesome, {babeldown} is a great pkg name and not confusing IMO.

@maelle
Copy link

maelle commented Sep 9, 2024

Since sometimes I use the wrong name, I am not so sure 😂

@e-kotov
Copy link
Member

e-kotov commented Oct 3, 2024

I have not touched the docs yet, but I am adding en/es sql files that transform the underlying CSV data in one of the branches to support output of tables in either Spanish or English.

@e-kotov e-kotov added this to the bilingual package milestone Oct 3, 2024
@e-kotov e-kotov added the enhancement New feature or request label Oct 3, 2024
@yabellini
Copy link

Hi!, thanks @maelle, for tagging me here.

I am available if I can be of any help. We also have a glossary to decide the technical terms we will translate and how: https://translationguide.ropensci.org/es/specific_guidelines.es.html#glosario-es

There are links to other glossaries with more terms from other translation projects.

@Robinlovelace
Copy link
Collaborator Author

That would be most appreciated @yabellini thank you! It's probably worth waiting for us to 'get our house in order' and possibly for a CRAN release signifying that the package has reached a level of maturity before starting translation to reduce maintenance/re-translation time is my guess but bit thumbs up and great to know there's expertise out there to help 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request help wanted Extra attention is needed
Projects
None yet
Milestone
bilingual package
Development

No branches or pull requests
5 participants
@Robinlovelace @yabellini @llrs @maelle @e-kotov