Translations chapter for the guide #63
Conversation
|
This looks fantastic! - I have also been writing the same chapter as part of the GSoD 2022 project. |
|
Hi @MichaelChirico this looks like a good start. For non-experts on gettext files, it would be useful to see a figure (node and edge diagram, nodes for files, edges for people/programs that create those files) or example (list of all files relevant to a given domain, in the source tree) to explain the relationship of the various files (pot, po, mo). |
Please do!
Great point! |
13-translations.Rmd
Outdated
|
|
||
| ## How translations work | ||
|
|
||
| Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, |
There was a problem hiding this comment.
| Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, | |
| There are two basic files with extensions `.pot` and `.po` that are usually required during the Translation process in R. The `.pot` files are the template files which contain the error messages, warnings, and other similar messages, in R. In the template `.pot` file these messages will be available in standard English against the placeholder `msgid "Standard English message is placed here"`. Below every `msgid` there will be a placeholder for the translated message called `msgstr ""` and it would always be empty (default) in the `.pot` file. The `msgstr` is to be filled in the corresponding `.po` file - to include the appropriate translation. Both the template `.pot` file and the translated `.po` file should stored in the same directory always. Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, |
There was a problem hiding this comment.
Could you add a link to an example .pot and .po file at the SVN repo? May help curious readers quickly see what these files look like and what to expect.
There was a problem hiding this comment.
implementation question -- what sort of link would be appropriate? Is a relative link possible? Or should we be perma-linking a commit from the r-devel/r-svn repo?
There was a problem hiding this comment.
Or maybe just copy/paste a couple of lines from each as two code blocks? Something like
| Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, | |
| There are two basic files with extensions `.pot` and `.po` that are usually required during the Translation process in R. The `.pot` files are the template files which contain the error messages, warnings, and other similar messages, in R. In the template `.pot` file these messages will be available in standard English against the placeholder `msgid "Standard English message is placed here"`. Below every `msgid` there will be a placeholder for the translated message called `msgstr ""` and it would always be empty (default) in the `.pot` file. As an example, we look at how the string "Warning:" can be translated to other languages: | |
| ``` | |
| #: src/main/errors.c:491 | |
| msgid "Warning:" | |
| msgstr "" | |
| ``` | |
| Which is taken from `po/R.pot` and the corresponding German translation | |
| ``` | |
| #: src/main/errors.c:491 | |
| msgid "Warning:" | |
| msgstr "Warnung:" | |
| ``` | |
| at `po/de.po`. Both the template `.pot` file and the translated `.po` file should stored in the same directory always. Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, |
|
@MichaelChirico - I've added some stuff in the chapter Also this could be placed as chapter 8, that is, after the Documenting R chapter and before the Testing pre release R versions chapter - what do you think? |
|
Once the chapter number is decided, can we open this for review? |
SaranjeetKaur
changed the title
Co-authored-by: Saranjeet Kaur <[email protected]>
13-translations.Rmd
Outdated
|
|
||
| ## How translations work | ||
|
|
||
| Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, |
There was a problem hiding this comment.
Or maybe just copy/paste a couple of lines from each as two code blocks? Something like
| Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, | |
| There are two basic files with extensions `.pot` and `.po` that are usually required during the Translation process in R. The `.pot` files are the template files which contain the error messages, warnings, and other similar messages, in R. In the template `.pot` file these messages will be available in standard English against the placeholder `msgid "Standard English message is placed here"`. Below every `msgid` there will be a placeholder for the translated message called `msgstr ""` and it would always be empty (default) in the `.pot` file. As an example, we look at how the string "Warning:" can be translated to other languages: | |
| ``` | |
| #: src/main/errors.c:491 | |
| msgid "Warning:" | |
| msgstr "" | |
| ``` | |
| Which is taken from `po/R.pot` and the corresponding German translation | |
| ``` | |
| #: src/main/errors.c:491 | |
| msgid "Warning:" | |
| msgstr "Warnung:" | |
| ``` | |
| at `po/de.po`. Both the template `.pot` file and the translated `.po` file should stored in the same directory always. Each of the default packages distributed with R (i.e., those found in `./src/library` such as `base`, `utils`, |
|
Sorry, the history's a bit hard to follow now that some of the comments are marked as Outdated. If you think I'm missing addressing something, please ping again. More progress here... |
08-translations.Rmd
Outdated
|
|
||
| The `.pot` file is a snapshot of the messages available in a given **domain**. A domain in R typically identifies | ||
| a source package and a source language (either R or C/C++). For example, the file `R-base.pot` | ||
| (found in the R sources in `./src/library/base/po`) is a catalogue of all messages produced by R code in the |
There was a problem hiding this comment.
could make this a hyperlink to https://svn.r-project.org/R/trunk/src/library/base/po/, also elsewhere
There was a problem hiding this comment.
Should we prefer a link to the svn trunk, or the GH mirror trunk? Former is more official of course, latter comes with syntax highlighting/other tooling integration, web-navigable history/blame, etc...
There was a problem hiding this comment.
Yes, my first thought was that we should link to the official sources, but I like your later use of linking to highlighted lines and in general the GH mirror is easier to browse.
So, perhaps we can go with linking to the GH mirror whenever we just expect people to read the files in the browser (as throughout this chapter). To be very clear about it, we could add a footnote to the first link, to say that we are linking to the GH mirror in this chapter as it is a better interface for browsing the source files and link to the actual svn repo there (https://svn.r-project.org/R/trunk/)
|
The existing sections seem nearly done. It could be good to finishing tidying those and merge them in before filling in new sections as I think the description of the .po/.poedit files will already be useful for people that are starting to contribute via weblate (c.f. #68). |
Great idea, better to have something ready to refer to now that the translations are picking up a lot more traffic. That can also help direct efforts on where there are remaining points of confusion. |
Co-authored-by: Heather Turner <[email protected]>
|
@SaranjeetKaur / @hturner thanks for both your reviews; let me know when you're happy to merge this initial version. |
|
@all-contributors please add @MichaelChirico for content, doc, research |
|
I've put up a pull request to add @MichaelChirico! 🎉 |
|
@all-contributors please add @bettinagruen for review, research, question |
|
I've put up a pull request to add @bettinagruen! 🎉 |
|
@all-contributors please add @nbenn for review, research, question |
|
I've put up a pull request to add @nbenn! 🎉 |
|
@all-contributors please add @benubah for content, review, research, question |
|
I've put up a pull request to add @benubah! 🎉 |
|
@all-contributors please add @tdhock for review, research, question |
|
I've put up a pull request to add @tdhock! 🎉 |
|
All the open comments and reviews on this chapter which might need further dicussions and work are now opened as new issues (with links to the original comment or review). As of now, I'm merging this PR so that the translations chapter is up on the devguide. @MichaelChirico thank you for your contributions! :) |
Closes #34