From 273800700beca99133a95b8577ed0cf688497a74 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 10:32:33 +0000 Subject: [PATCH 01/10] change .Rmd to .qmd and names to lower --- _bookdown.yml | 10 ---------- 15-developer_tools.Rmd => developer_tools.qmd | 0 09-documenting.Rmd => documenting.qmd | 0 07-finding_the_source.Rmd => finding_the_source.qmd | 0 02-getting_started.Rmd => getting_started.qmd | 0 index.Rmd => index.qmd | 0 01-Introduction.Rmd => introduction.qmd | 0 03-issue_tracking.Rmd => issue_tracking.qmd | 0 ...ifecycle_of_a_Patch.Rmd => lifecycle_of_a_patch.qmd | 0 ...essage-translations.Rmd => message-translations.qmd | 0 ...and_announcements.Rmd => news_and_announcements.qmd | 0 12-R_Core_Developers.Rmd => r_core_developers.qmd | 0 04-reporting_bugs.Rmd => reporting_bugs.qmd | 0 06-reviewing_bugs.Rmd => reviewing_bugs.qmd | 0 ...ure_requests.Rmd => submitting_feature_requests.qmd | 0 ..._versions.Rmd => testing_pre_release_r_versions.qmd | 0 13-where_to_get_help.Rmd => where_to_get_help.qmd | 0 17 files changed, 10 deletions(-) delete mode 100644 _bookdown.yml rename 15-developer_tools.Rmd => developer_tools.qmd (100%) rename 09-documenting.Rmd => documenting.qmd (100%) rename 07-finding_the_source.Rmd => finding_the_source.qmd (100%) rename 02-getting_started.Rmd => getting_started.qmd (100%) rename index.Rmd => index.qmd (100%) rename 01-Introduction.Rmd => introduction.qmd (100%) rename 03-issue_tracking.Rmd => issue_tracking.qmd (100%) rename 08-lifecycle_of_a_Patch.Rmd => lifecycle_of_a_patch.qmd (100%) rename 10-message-translations.Rmd => message-translations.qmd (100%) rename 14-news_and_announcements.Rmd => news_and_announcements.qmd (100%) rename 12-R_Core_Developers.Rmd => r_core_developers.qmd (100%) rename 04-reporting_bugs.Rmd => reporting_bugs.qmd (100%) rename 06-reviewing_bugs.Rmd => reviewing_bugs.qmd (100%) rename 05-submitting_feature_requests.Rmd => submitting_feature_requests.qmd (100%) rename 11-testing_pre_release_R_versions.Rmd => testing_pre_release_r_versions.qmd (100%) rename 13-where_to_get_help.Rmd => where_to_get_help.qmd (100%) diff --git a/_bookdown.yml b/_bookdown.yml deleted file mode 100644 index b21919d3..00000000 --- a/_bookdown.yml +++ /dev/null @@ -1,10 +0,0 @@ -book_filename: "rdevguide" -chapter_name: "Chapter " -repo: https://github.com/r-devel/rdevguide -url: 'https\://contributor.r-project.org/rdevguide/' -github-repo: "r-devel/rdevguide" -output_dir: docs -clean: [packages.bib, bookdown.bbl] -new_session: yes -edit: https://github.com/r-devel/rdevguide/edit/main/%s -delete_merged_file: true diff --git a/15-developer_tools.Rmd b/developer_tools.qmd similarity index 100% rename from 15-developer_tools.Rmd rename to developer_tools.qmd diff --git a/09-documenting.Rmd b/documenting.qmd similarity index 100% rename from 09-documenting.Rmd rename to documenting.qmd diff --git a/07-finding_the_source.Rmd b/finding_the_source.qmd similarity index 100% rename from 07-finding_the_source.Rmd rename to finding_the_source.qmd diff --git a/02-getting_started.Rmd b/getting_started.qmd similarity index 100% rename from 02-getting_started.Rmd rename to getting_started.qmd diff --git a/index.Rmd b/index.qmd similarity index 100% rename from index.Rmd rename to index.qmd diff --git a/01-Introduction.Rmd b/introduction.qmd similarity index 100% rename from 01-Introduction.Rmd rename to introduction.qmd diff --git a/03-issue_tracking.Rmd b/issue_tracking.qmd similarity index 100% rename from 03-issue_tracking.Rmd rename to issue_tracking.qmd diff --git a/08-lifecycle_of_a_Patch.Rmd b/lifecycle_of_a_patch.qmd similarity index 100% rename from 08-lifecycle_of_a_Patch.Rmd rename to lifecycle_of_a_patch.qmd diff --git a/10-message-translations.Rmd b/message-translations.qmd similarity index 100% rename from 10-message-translations.Rmd rename to message-translations.qmd diff --git a/14-news_and_announcements.Rmd b/news_and_announcements.qmd similarity index 100% rename from 14-news_and_announcements.Rmd rename to news_and_announcements.qmd diff --git a/12-R_Core_Developers.Rmd b/r_core_developers.qmd similarity index 100% rename from 12-R_Core_Developers.Rmd rename to r_core_developers.qmd diff --git a/04-reporting_bugs.Rmd b/reporting_bugs.qmd similarity index 100% rename from 04-reporting_bugs.Rmd rename to reporting_bugs.qmd diff --git a/06-reviewing_bugs.Rmd b/reviewing_bugs.qmd similarity index 100% rename from 06-reviewing_bugs.Rmd rename to reviewing_bugs.qmd diff --git a/05-submitting_feature_requests.Rmd b/submitting_feature_requests.qmd similarity index 100% rename from 05-submitting_feature_requests.Rmd rename to submitting_feature_requests.qmd diff --git a/11-testing_pre_release_R_versions.Rmd b/testing_pre_release_r_versions.qmd similarity index 100% rename from 11-testing_pre_release_R_versions.Rmd rename to testing_pre_release_r_versions.qmd diff --git a/13-where_to_get_help.Rmd b/where_to_get_help.qmd similarity index 100% rename from 13-where_to_get_help.Rmd rename to where_to_get_help.qmd From 6ce62b2159fe5d63aa345b2c75cc82d20f69e311 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 11:12:02 +0000 Subject: [PATCH 02/10] _quarto.yml setup --- _quarto.yml | 52 ++++++ message_translations.qmd | 355 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 407 insertions(+) create mode 100644 _quarto.yml create mode 100644 message_translations.qmd diff --git a/_quarto.yml b/_quarto.yml new file mode 100644 index 00000000..a09c2945 --- /dev/null +++ b/_quarto.yml @@ -0,0 +1,52 @@ +project: + type: book + +book: + title: "R Development Guide" + author: "R Contribution Working Group" + date: today + favicon: img/favicon.png + site-url: https://contributor.r-project.org/rdevguide + repo-url: https://github.com/r-devel/rdevguide + repo-branch: main + repo-actions: [edit, issue] + chapters: + - index.qmd + - introduction.qmd + - getting_started.qmd + - issue_tracking.qmd + - reporting_bugs.qmd + - submitting_feature_requests.qmd + - reviewing_bugs.qmd + - finding_the_source.qmd + - lifecycle_of_a_patch.qmd + - documenting.qmd + - message_translations.qmd + - testing_pre_release_r_versions.qmd + - r_core_developers.qmd + - where_to_get_help.qmd + - news_and_announcements.qmd + - developer_tools.qmd + +format: + html: + theme: cosmo + include-in-header: header.html + description-meta: "This guide is a comprehensive resource for contributors (from all levels, beginners, intermediate, and seasoned) to the R project, facilitating their onboarding and helping them navigate the contribution process." + pdf: + documentclass: scrreprt + include-in-header: preamble.tex + include-before-body: frontpage.tex + epub: + cover-image: img/cover_page_sciberia.png + +# book_filename: "rdevguide" +# chapter_name: "Chapter " +# repo: https://github.com/r-devel/rdevguide +# url: 'https\://contributor.r-project.org/rdevguide/' +# github-repo: "r-devel/rdevguide" +# output_dir: docs +# clean: [packages.bib, bookdown.bbl] +# new_session: yes +# edit: https://github.com/r-devel/rdevguide/edit/main/%s +# delete_merged_file: true diff --git a/message_translations.qmd b/message_translations.qmd new file mode 100644 index 00000000..545a75a7 --- /dev/null +++ b/message_translations.qmd @@ -0,0 +1,355 @@ +--- +editor_options: + markdown: + wrap: 72 +--- + +# Message Translations + +This chapter covers internationalization in R, i.e., the display of +messages in languages other than English. All output in R (such as +messages emitted by `stop()`, `warning()`, or `message()`) is eligible +for translation, as are menu labels in the GUI. Depending on the version +of R that you are using, some of the languages might already be +available while others may need work. R leverages the +[`gettext`](https://www.gnu.org/software/gettext/) program to handle the +conversion from English to arbitrary target languages. + +Having messages available in other languages can be an important bridge +for R learners not confident in English -- rather than learning two +things at once (coding in R and processing diagnostic information in +English), they can focus on coding while getting more natural +errors/warnings in their native tongue. + +The [`gettext` +manual](https://www.gnu.org/software/gettext/manual/index.html) is a +more canonical reference for a deep understanding of how `gettext` +works. This chapter will just give a broad overview, with particular +focus on how things work for R, with the goal of making it as +low-friction as possible for developers and users to contribute +new/updated translations. + +## How translations work + +Each of the default packages distributed with R (i.e., those found in +`./src/library` such as `base`, `utils`, and `stats` and which have +priority base) contains a `po` directory. A `po` directory is the +central location for ataloguing/translating each package's messages. It +contains a template message file (`.pot`) for the corresponding ackage +along with translated `.po` files (that are created using the template +`.pot` file). + +### `.pot` files + +A `.pot` file is a template file found inside the `po` directory of an R +package. This template 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-stats.pot` (found in the R sources in `./src/library/stats/po`) is a +catalogue of all messages produced by R code in the `stats` package, +while `stats.pot` is a catalogue of all messages produced by C code in +the `stats` package. + +The 'base' package has two exceptions to the basic pattern described +above. The first is the domain for messages produced by the C code which +is the fundamental backing of R itself (especially, but not exclusively, +the C code under ./src/main[\^The file `./po/POTFILES` is the canonical +source of files searched. Note that while, technically, it is possible +to support translations in Fortran code, R does not currently do so. +Only a handful of messages are produced by Fortran routines in the R +sources.]). The associated `.pot` file is `R.pot` and is found in +`./src/library/base/po`. +R-base.pot`is a normal`.pot`file because base has a normal`R\` +directory. + +The second is the domain for the Windows R GUI, i.e., the text in the +menus and elsewhere in the R GUI program available for running R on +Windows. These messages are stored in the `RGui.pot` domain, also in the +`po` directory for `base`, and are most commonly derived from C code +found in `./src/gnuwin32`. One reason to keep this domain separate is +that it is only relevant to one platform (Windows). In particular, +Windows has historically different character encodings, so that it made +more sense for Windows developers to produce translations specifically +or Windows, since it is non-trivial for non-Windows users to test their +translations for the Windows GUI. + +#### Generating `.pot` files + +For outside contributors, there's no need to update .pot files -- +translators will typically take the R `.pot` files as given and generate +`.po` files. These will be sent along to a language-specific translation +maintainer, who then compiles them to send to the R Core developer +responsible for translations, who finally applies them as a patch. + +To emphasize, this section is almost always not needed for contributing +translations -- it is here for completeness and edification. + +### `.po` files + +.po files are the most important artifacts for translators. They provide +the (human-readable!) mapping between the messages as they appear in the +source code and how the messages will appear to users in translated +locales. + +#### Singular messages + +Most messages appear as `msgid`/`msgstr` pairs. The former gives the +message as it appears in the code, while the latter shows how it should +appear in translation. For example, here is an error in German (locale: +`de`) informing the user that their input must be of class `POSIXt` + +``` +msgid "'to' must be a \"POSIXt\" object" +msgstr "'to' muss ein \"POSIXt\" Objekt sein" +``` + +See this in context in the [`R-de.po` source +file](https://svn.r-project.org/R/trunk/src/library/base/po/R-de.po). + +The same message can also be found in +[`R-it.po`](https://svn.r-project.org/R/trunk/src/library/base/po/R-it.po) +giving the translation to Italian: + +``` +msgid "'to' must be a \"POSIXt\" object" +msgstr "'to' dev'essere un oggetto \"POSIXt\"" +``` + +#### Plural messages + +Some messages will have different translations depending on some input +determined at run time (e.g., the `length()` of an input object or the +`nrow()` of a `data.frame`). This presents a challenge for translation, +because different languages have different rules for how to pluralize +different ordinal numbers[\^See the [relevant +section](https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html) +of the `gettext` manual]. For example, English typically adds `s` to any +quantity of items besides 1 (1 dog, 2 dog`s`, 100 dog`s`, even 0 +dog`s`). Chinese typically does not alter the word itself in similar +situations (一只狗, 两只狗, 一百只狗, 零只狗); Arabic has *six* +different ways to pluralize a quantity. + +In `.po` files, this shows up in the form of `msgid_plural` entries, +followed by several ordered `msgstr` entries. Here's an example from +[`R-de.po`](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-de.po#L2015-L2018)[^09-message-translations-1]: + +[^09-message-translations-1]: The GitHub mirror of the [actual svn + repo](https://svn.r-project.org/R/trunk/) is linked in this chapter + as it is a better interface for browsing the source files. + +``` +msgid "Warning message:\n" +msgid_plural "Warning messages:\n" +msgstr[0] "Warnmeldung:\n" +msgstr[1] "Warnmeldungen:\n" +``` + +The two entries in English correspond to the singular and plural +messages; the two entries in German correspond similarly, because +pluralization rules in German are similar to those in English. The +situation in Lithuanian +([`R-lt.po`](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-lt.po#L1999-L2003)) +is more divergent: + +``` +msgid "Warning message:\n" +msgid_plural "Warning messages:\n" +msgstr[0] "Įspėjantis pranešimas:\n" +msgstr[1] "Įspėjantys pranešimai:\n" +msgstr[2] "Įspėjančių pranešimų:\n" +``` + +This corresponds to the 3 different ways to pluralize words in Polish. + +What do `0`, `1`, and `2` correspond to, exactly? Ideally, this will be +clear to native speakers of the language, but for clarity, it is the +solution to a small arithmetic problem that can be found in the +language's metadata entry. Look for the `Plural-Forms` entry in the +metadata at the top of the `.po` file; [here it is for +Lithuanian](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-lt.po#L18-L19): + +``` +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n" +"%100<10 || n%100>=20) ? 1 : 2);\n" +``` + +`nplurals` tells us how many entries correspond to each `msgid_plural` +for this language. `plural` tells us, for the quantity `n`, which entry +to use. The arithmetic is C code; most important if you really want to +parse this and are only familiar with R code is C's [ternary +operator](https://en.wikipedia.org/wiki/%3F:): +`test ? valueIfTrue : valueIfFalse` is a handy way to write R's +`if (test) valueIfTrue else valueIfFalse`. + +Parsing, we get the following associations: + +- the `0` entry corresponds to when a number equals 1 modulo 10 (i.e., + 1, 11, 21, 31, ...) *except* numbers equaling 11 modulo 100 (i.e., + 11, 111, 211, 311, ...). Combining, that's 1, 21, 31, ..., 91, 101, + 121, 131, ..., 191, ... +- the `1` entry corresponds to numbers at least 2 modulo 10 (2, 3, + ..., 8, 9, 12, 13, 14, ...) and *either* below 10 modulo 100 (0, 1, + ..., 9, 100, 101, ..., 109, ...) *or* exceeding 20 modulo 100 (21, + 22, ..., 99). Combining, that's 2, 3, ..., 9, 22, 23, ..., 29, 32, + 33, ... 39, ..., 102, 103, ..., 109, 122, 123, ... +- The `2` entry corresponds to all other numbers, i.e. 0, 10, 11, 12, + ..., 19, 20, 30, ..., 90, 100, 110, 111, 112, ... + + + + + + + +### `.mo` files + +`.po` files are plain text, but while helpful for human readers, this is +inefficient for consumption by computers. The .mo format is a "compiled" +version of the .po file optimized for retrieving messages when R is +running. + +In R-devel, the conversion from .po to .mo is done by R Core -- you +don't need to compile these files yourself. They are stored in the R +sources at `./src/library/translations/inst` in various +language-specific subdirectories. + +## How to contribute new translations + + + +Translating R into different languages helps make it more user-friendly +for non-English speakers and helps to grow the R community. See the blog +post on how [R can use your help: Translating R +messages](https://blog.r-project.org/2022/07/25/r-can-use-your-help-translating-r-messages). + +To get started contributing to translations, please follow the steps +below: + +**Step 1: Register an Account at Weblate** + +Weblate is an open-source platform for collaborative translation of +software projects. Register an account on R's Weblate server, +, to start contributing. + +> *Note: To get started follow the detailed workflow and convention for +> translation which is given here: +> * + +**Step 2: Choose a Component and Language** + +Select a component of R with less than 100% translation. Each component +corresponds to the messages in either the R code or the C code of one of +the packages in base R, e.g. base (R files), or tools (C files). There +is one special case: base (R GUI), which corresponds to the messages in +the Windows Graphical User Interface. + +After selecting a component, you can select your preferred language. + +![](img/translate_component.png) + + + + + + + + + + + + + +**Step 3: Translate the Message** + +Now, you can click on Translate button on your right. + +> Note: More information for String status visit: +> + +![](img/translate_button.png) + +Then, start translating the message by typing the translation in the +text box. + +![](img/translate_string_and_save.png) + +- If you are **confident** that the **translation is correct**, make + sure the "Needs editing" box is **unchecked**. + +- If you are **unsure** about how to translate, write the translation + as a **Suggest** button instead. + +- Finally, Click **"Save and Continue"** to save the translation and + continue. + +------------------------------------------------------------------------ + +> **Note:** Use Glossary feature within Weblate making translation easy +> and consistent: +> + +> **Note:** Make sure to use Automatic Suggestions as a starting point. + +1. Click on Automatic Suggestions (machine translation) + +2. Accept it if you think the automatic suggestion looks good + +![](img/auto-suggestion.png) + +------------------------------------------------------------------------ + +**Some Tips to follow:** + +- **Be consistent:** Use the same words and phrases throughout the + translation to make it consistent and avoid confusion. + +- **Check for technical issues:** After finishing the translation, + check if you have any alerts or warning in the Weblate string + status, e.g. double instead of single space. + +- **Follow language specific guidelines:** Check how other languages + have translated the string. Even if you are not fluent in another + language it can give you an idea of how other translators have + handled it, especially which parts are left verbatim. A detailed + guide is given here : + [Conventions-for-translations#languages-and-contributions](https://contributor.r-project.org/translations/Conventions_for_Languages/#languages-and-contributions){.uri} + +Related links: + + + +## Bulk Translations + +Instead of translating one string at a time, it is possible to bulk translate a whole component of R at once: + +1. Navigate to the translations for a particular component in a particular language, e.g. https://translate.rx.studio/projects/r-project/base-c/ar/ + +2. Select **'Tools > Automatic translation'** + +![Tools drop-down menu with "Automatic Translations" selected](img/translate_automatic_translation.png) + + +3. In the dialog, + - under **'Automatic translation mode'**, select **'Add as "needing edit"'**[^09-message-translations-2]: + + +[^09-message-translations-2]: By selecting **'Add as "needing edit"'**, the autotranslated strings would be treated as "fuzzy" translations, i.e. they would be added to the component source files when a patch is made, but they would NOT be used. + + - under **'Search filter'**, select **'Untranslated strings'** + - under **'Source of automated translations'**, select **'Machine translation'** + - under **'Machine translation engines'**, select **'Microsoft Translator'**[^09-message-translations-3]: + + +[^09-message-translations-3]: Microsoft Translator is preferred for bulk translation as our free tier covers 2 million characters/month, where DeepL only allows 500k chars/month. If Microsoft Translator translations are much worse than DeepL, it may be useful to use it to translate one string at a time. + +![Automatic Translations dialog box](img/translate_dialog.png) + +4. Review the translations, edit as necessary and uncheck **"needing edit"**. + +## Current status of translations in R + + + +## Helpful references + +- Statistical terms glossary From 556184c7fa2c9ea28700e1d76393bdd2e413cee1 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 11:12:26 +0000 Subject: [PATCH 03/10] remove yml from index.qmd --- index.qmd | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/index.qmd b/index.qmd index f0c43fbb..ca98aa02 100644 --- a/index.qmd +++ b/index.qmd @@ -1,21 +1,3 @@ ---- -title: "R Development Guide" -author: "R Contribution Working Group" -date: "`r Sys.Date()`" -site: bookdown::bookdown_site -output: bookdown::gitbook -documentclass: book -bibliography: [book.bib] -biblio-style: apalike -link-citations: yes -github-repo: r-devel/rdevguide -url: https://contributor.r-project.org/rdevguide -cover-image: "img/cover_page_scriberia.png" -favicon: "img/Rlogo.svg" -description: "This guide is a comprehensive resource for contributors (from all levels, beginners, intermediate, and seasoned) to the R project, facilitating their onboarding and helping them navigate the contribution process." - ---- - # {-} ![R Development Guide. This illustration is created by Scriberia with The Turing Way community, used under a CC-BY 4.0 licence. DOI:= https://zenodo.org/records/13882307](img/r-development-guide.jpg){height=400px width=550px} From b4c12c4bac346a3b74c7929ac3f503f3d8678423 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 11:13:06 +0000 Subject: [PATCH 04/10] callout-note --- message-translations.qmd | 355 --------------------------------------- reviewing_bugs.qmd | 6 +- 2 files changed, 3 insertions(+), 358 deletions(-) delete mode 100644 message-translations.qmd diff --git a/message-translations.qmd b/message-translations.qmd deleted file mode 100644 index 545a75a7..00000000 --- a/message-translations.qmd +++ /dev/null @@ -1,355 +0,0 @@ ---- -editor_options: - markdown: - wrap: 72 ---- - -# Message Translations - -This chapter covers internationalization in R, i.e., the display of -messages in languages other than English. All output in R (such as -messages emitted by `stop()`, `warning()`, or `message()`) is eligible -for translation, as are menu labels in the GUI. Depending on the version -of R that you are using, some of the languages might already be -available while others may need work. R leverages the -[`gettext`](https://www.gnu.org/software/gettext/) program to handle the -conversion from English to arbitrary target languages. - -Having messages available in other languages can be an important bridge -for R learners not confident in English -- rather than learning two -things at once (coding in R and processing diagnostic information in -English), they can focus on coding while getting more natural -errors/warnings in their native tongue. - -The [`gettext` -manual](https://www.gnu.org/software/gettext/manual/index.html) is a -more canonical reference for a deep understanding of how `gettext` -works. This chapter will just give a broad overview, with particular -focus on how things work for R, with the goal of making it as -low-friction as possible for developers and users to contribute -new/updated translations. - -## How translations work - -Each of the default packages distributed with R (i.e., those found in -`./src/library` such as `base`, `utils`, and `stats` and which have -priority base) contains a `po` directory. A `po` directory is the -central location for ataloguing/translating each package's messages. It -contains a template message file (`.pot`) for the corresponding ackage -along with translated `.po` files (that are created using the template -`.pot` file). - -### `.pot` files - -A `.pot` file is a template file found inside the `po` directory of an R -package. This template 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-stats.pot` (found in the R sources in `./src/library/stats/po`) is a -catalogue of all messages produced by R code in the `stats` package, -while `stats.pot` is a catalogue of all messages produced by C code in -the `stats` package. - -The 'base' package has two exceptions to the basic pattern described -above. The first is the domain for messages produced by the C code which -is the fundamental backing of R itself (especially, but not exclusively, -the C code under ./src/main[\^The file `./po/POTFILES` is the canonical -source of files searched. Note that while, technically, it is possible -to support translations in Fortran code, R does not currently do so. -Only a handful of messages are produced by Fortran routines in the R -sources.]). The associated `.pot` file is `R.pot` and is found in -`./src/library/base/po`. -R-base.pot`is a normal`.pot`file because base has a normal`R\` -directory. - -The second is the domain for the Windows R GUI, i.e., the text in the -menus and elsewhere in the R GUI program available for running R on -Windows. These messages are stored in the `RGui.pot` domain, also in the -`po` directory for `base`, and are most commonly derived from C code -found in `./src/gnuwin32`. One reason to keep this domain separate is -that it is only relevant to one platform (Windows). In particular, -Windows has historically different character encodings, so that it made -more sense for Windows developers to produce translations specifically -or Windows, since it is non-trivial for non-Windows users to test their -translations for the Windows GUI. - -#### Generating `.pot` files - -For outside contributors, there's no need to update .pot files -- -translators will typically take the R `.pot` files as given and generate -`.po` files. These will be sent along to a language-specific translation -maintainer, who then compiles them to send to the R Core developer -responsible for translations, who finally applies them as a patch. - -To emphasize, this section is almost always not needed for contributing -translations -- it is here for completeness and edification. - -### `.po` files - -.po files are the most important artifacts for translators. They provide -the (human-readable!) mapping between the messages as they appear in the -source code and how the messages will appear to users in translated -locales. - -#### Singular messages - -Most messages appear as `msgid`/`msgstr` pairs. The former gives the -message as it appears in the code, while the latter shows how it should -appear in translation. For example, here is an error in German (locale: -`de`) informing the user that their input must be of class `POSIXt` - -``` -msgid "'to' must be a \"POSIXt\" object" -msgstr "'to' muss ein \"POSIXt\" Objekt sein" -``` - -See this in context in the [`R-de.po` source -file](https://svn.r-project.org/R/trunk/src/library/base/po/R-de.po). - -The same message can also be found in -[`R-it.po`](https://svn.r-project.org/R/trunk/src/library/base/po/R-it.po) -giving the translation to Italian: - -``` -msgid "'to' must be a \"POSIXt\" object" -msgstr "'to' dev'essere un oggetto \"POSIXt\"" -``` - -#### Plural messages - -Some messages will have different translations depending on some input -determined at run time (e.g., the `length()` of an input object or the -`nrow()` of a `data.frame`). This presents a challenge for translation, -because different languages have different rules for how to pluralize -different ordinal numbers[\^See the [relevant -section](https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html) -of the `gettext` manual]. For example, English typically adds `s` to any -quantity of items besides 1 (1 dog, 2 dog`s`, 100 dog`s`, even 0 -dog`s`). Chinese typically does not alter the word itself in similar -situations (一只狗, 两只狗, 一百只狗, 零只狗); Arabic has *six* -different ways to pluralize a quantity. - -In `.po` files, this shows up in the form of `msgid_plural` entries, -followed by several ordered `msgstr` entries. Here's an example from -[`R-de.po`](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-de.po#L2015-L2018)[^09-message-translations-1]: - -[^09-message-translations-1]: The GitHub mirror of the [actual svn - repo](https://svn.r-project.org/R/trunk/) is linked in this chapter - as it is a better interface for browsing the source files. - -``` -msgid "Warning message:\n" -msgid_plural "Warning messages:\n" -msgstr[0] "Warnmeldung:\n" -msgstr[1] "Warnmeldungen:\n" -``` - -The two entries in English correspond to the singular and plural -messages; the two entries in German correspond similarly, because -pluralization rules in German are similar to those in English. The -situation in Lithuanian -([`R-lt.po`](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-lt.po#L1999-L2003)) -is more divergent: - -``` -msgid "Warning message:\n" -msgid_plural "Warning messages:\n" -msgstr[0] "Įspėjantis pranešimas:\n" -msgstr[1] "Įspėjantys pranešimai:\n" -msgstr[2] "Įspėjančių pranešimų:\n" -``` - -This corresponds to the 3 different ways to pluralize words in Polish. - -What do `0`, `1`, and `2` correspond to, exactly? Ideally, this will be -clear to native speakers of the language, but for clarity, it is the -solution to a small arithmetic problem that can be found in the -language's metadata entry. Look for the `Plural-Forms` entry in the -metadata at the top of the `.po` file; [here it is for -Lithuanian](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-lt.po#L18-L19): - -``` -"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n" -"%100<10 || n%100>=20) ? 1 : 2);\n" -``` - -`nplurals` tells us how many entries correspond to each `msgid_plural` -for this language. `plural` tells us, for the quantity `n`, which entry -to use. The arithmetic is C code; most important if you really want to -parse this and are only familiar with R code is C's [ternary -operator](https://en.wikipedia.org/wiki/%3F:): -`test ? valueIfTrue : valueIfFalse` is a handy way to write R's -`if (test) valueIfTrue else valueIfFalse`. - -Parsing, we get the following associations: - -- the `0` entry corresponds to when a number equals 1 modulo 10 (i.e., - 1, 11, 21, 31, ...) *except* numbers equaling 11 modulo 100 (i.e., - 11, 111, 211, 311, ...). Combining, that's 1, 21, 31, ..., 91, 101, - 121, 131, ..., 191, ... -- the `1` entry corresponds to numbers at least 2 modulo 10 (2, 3, - ..., 8, 9, 12, 13, 14, ...) and *either* below 10 modulo 100 (0, 1, - ..., 9, 100, 101, ..., 109, ...) *or* exceeding 20 modulo 100 (21, - 22, ..., 99). Combining, that's 2, 3, ..., 9, 22, 23, ..., 29, 32, - 33, ... 39, ..., 102, 103, ..., 109, 122, 123, ... -- The `2` entry corresponds to all other numbers, i.e. 0, 10, 11, 12, - ..., 19, 20, 30, ..., 90, 100, 110, 111, 112, ... - - - - - - - -### `.mo` files - -`.po` files are plain text, but while helpful for human readers, this is -inefficient for consumption by computers. The .mo format is a "compiled" -version of the .po file optimized for retrieving messages when R is -running. - -In R-devel, the conversion from .po to .mo is done by R Core -- you -don't need to compile these files yourself. They are stored in the R -sources at `./src/library/translations/inst` in various -language-specific subdirectories. - -## How to contribute new translations - - - -Translating R into different languages helps make it more user-friendly -for non-English speakers and helps to grow the R community. See the blog -post on how [R can use your help: Translating R -messages](https://blog.r-project.org/2022/07/25/r-can-use-your-help-translating-r-messages). - -To get started contributing to translations, please follow the steps -below: - -**Step 1: Register an Account at Weblate** - -Weblate is an open-source platform for collaborative translation of -software projects. Register an account on R's Weblate server, -, to start contributing. - -> *Note: To get started follow the detailed workflow and convention for -> translation which is given here: -> * - -**Step 2: Choose a Component and Language** - -Select a component of R with less than 100% translation. Each component -corresponds to the messages in either the R code or the C code of one of -the packages in base R, e.g. base (R files), or tools (C files). There -is one special case: base (R GUI), which corresponds to the messages in -the Windows Graphical User Interface. - -After selecting a component, you can select your preferred language. - -![](img/translate_component.png) - - - - - - - - - - - - - -**Step 3: Translate the Message** - -Now, you can click on Translate button on your right. - -> Note: More information for String status visit: -> - -![](img/translate_button.png) - -Then, start translating the message by typing the translation in the -text box. - -![](img/translate_string_and_save.png) - -- If you are **confident** that the **translation is correct**, make - sure the "Needs editing" box is **unchecked**. - -- If you are **unsure** about how to translate, write the translation - as a **Suggest** button instead. - -- Finally, Click **"Save and Continue"** to save the translation and - continue. - ------------------------------------------------------------------------- - -> **Note:** Use Glossary feature within Weblate making translation easy -> and consistent: -> - -> **Note:** Make sure to use Automatic Suggestions as a starting point. - -1. Click on Automatic Suggestions (machine translation) - -2. Accept it if you think the automatic suggestion looks good - -![](img/auto-suggestion.png) - ------------------------------------------------------------------------- - -**Some Tips to follow:** - -- **Be consistent:** Use the same words and phrases throughout the - translation to make it consistent and avoid confusion. - -- **Check for technical issues:** After finishing the translation, - check if you have any alerts or warning in the Weblate string - status, e.g. double instead of single space. - -- **Follow language specific guidelines:** Check how other languages - have translated the string. Even if you are not fluent in another - language it can give you an idea of how other translators have - handled it, especially which parts are left verbatim. A detailed - guide is given here : - [Conventions-for-translations#languages-and-contributions](https://contributor.r-project.org/translations/Conventions_for_Languages/#languages-and-contributions){.uri} - -Related links: - - - -## Bulk Translations - -Instead of translating one string at a time, it is possible to bulk translate a whole component of R at once: - -1. Navigate to the translations for a particular component in a particular language, e.g. https://translate.rx.studio/projects/r-project/base-c/ar/ - -2. Select **'Tools > Automatic translation'** - -![Tools drop-down menu with "Automatic Translations" selected](img/translate_automatic_translation.png) - - -3. In the dialog, - - under **'Automatic translation mode'**, select **'Add as "needing edit"'**[^09-message-translations-2]: - - -[^09-message-translations-2]: By selecting **'Add as "needing edit"'**, the autotranslated strings would be treated as "fuzzy" translations, i.e. they would be added to the component source files when a patch is made, but they would NOT be used. - - - under **'Search filter'**, select **'Untranslated strings'** - - under **'Source of automated translations'**, select **'Machine translation'** - - under **'Machine translation engines'**, select **'Microsoft Translator'**[^09-message-translations-3]: - - -[^09-message-translations-3]: Microsoft Translator is preferred for bulk translation as our free tier covers 2 million characters/month, where DeepL only allows 500k chars/month. If Microsoft Translator translations are much worse than DeepL, it may be useful to use it to translate one string at a time. - -![Automatic Translations dialog box](img/translate_dialog.png) - -4. Review the translations, edit as necessary and uncheck **"needing edit"**. - -## Current status of translations in R - - - -## Helpful references - -- Statistical terms glossary diff --git a/reviewing_bugs.qmd b/reviewing_bugs.qmd index 0525a5b9..9b601443 100644 --- a/reviewing_bugs.qmd +++ b/reviewing_bugs.qmd @@ -36,11 +36,11 @@ These helpful tasks allow the Core developers and/ or maintainers to classify a ## Example of a bug review submitted on Bugzilla -If you would like to see how bugs are reviewed on Bugzilla, the [Bug 16542 - nlme:::summary.lmList with unequal outputs per group](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=16542) is an example where an old bug report is being reviewed. It is tested to see if it was still an issue and a few ways are proposed to resolve the issue. - -**Note**: +If you would like to see how bugs are reviewed on Bugzilla, the [Bug 16542 - `nlme:::summary.lmList` with unequal outputs per group](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=16542) is an example where an old bug report is being reviewed. It is tested to see if it was still an issue and a few ways are proposed to resolve the issue. +::: {.callout-note} There is a `#bug-reporting` channel on the [R Contributors slack](https://r-contributors.slack.com/) where you can share your bug report(s) for review/feedback before submitting to Bugzilla. This can help with checking that it really is a bug, that you have included the important information and excluded redundant information. +::: ## See also From 45a25d5fe9d649d907402d2dffb53b78a5fa5056 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 11:13:18 +0000 Subject: [PATCH 05/10] update header.html --- header.html | 7 ------- 1 file changed, 7 deletions(-) diff --git a/header.html b/header.html index 73b0fd78..28d98f1f 100644 --- a/header.html +++ b/header.html @@ -1,10 +1,3 @@ - - From 50ca909540ccf3ac33da3b74300dfb047e91953b Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 11:13:26 +0000 Subject: [PATCH 06/10] gitignore _book --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index fdc14a78..1d874be4 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,6 @@ rdevguide.tex # temp files *~ + +/.quarto/ +_book \ No newline at end of file From 35013767e2274f04533093251d550204f6213c76 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 11:17:08 +0000 Subject: [PATCH 07/10] Delete _output.yml --- _output.yml | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 _output.yml diff --git a/_output.yml b/_output.yml deleted file mode 100644 index 9823f6b1..00000000 --- a/_output.yml +++ /dev/null @@ -1,26 +0,0 @@ -bookdown::gitbook: - include: - in_header: header.html - css: style.css - split_by: chapter - config: - sharing: - github: true - facebook: false - twitter: false - toc: - collapse: subsection - after: | -
  • Published with bookdown
    • - download: ["pdf", "epub"] - edit: https://github.com/r-devel/rdevguide/edit/main/%s - view: https://github.com/r-devel/rdevguide/blob/main/%s - history: https://github.com/r-devel/rdevguide/commits/main/%s -bookdown::pdf_book: - includes: - in_header: preamble.tex - before_body: frontpage.tex - latex_engine: xelatex - citation_package: natbib - keep_tex: yes -bookdown::epub_book: default From 75c6a75f072e93fb37be1850ccf634cad4f8f1a0 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 14:01:40 +0000 Subject: [PATCH 08/10] No R logo on first image --- index.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.qmd b/index.qmd index ca98aa02..5bdb2412 100644 --- a/index.qmd +++ b/index.qmd @@ -1,6 +1,6 @@ # {-} -![R Development Guide. This illustration is created by Scriberia with The Turing Way community, used under a CC-BY 4.0 licence. DOI:= https://zenodo.org/records/13882307](img/r-development-guide.jpg){height=400px width=550px} +![R Development Guide. This illustration is created by Scriberia with The Turing Way community, used under a CC-BY 4.0 licence. DOI:= https://zenodo.org/records/13882307](img/r-dev-guide-without-text.jpg){height=400px width=550px} # Acknowledgement {-} From ea5deee521a4398c4f9af89e5ba20bb74861736b Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 14:08:04 +0000 Subject: [PATCH 09/10] Fix typo --- _quarto.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_quarto.yml b/_quarto.yml index a09c2945..561939f2 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -38,7 +38,7 @@ format: include-in-header: preamble.tex include-before-body: frontpage.tex epub: - cover-image: img/cover_page_sciberia.png + cover-image: img/cover_page_scriberia.png # book_filename: "rdevguide" # chapter_name: "Chapter " From b03b65043f0167bff285ea8cf9cec63f395de150 Mon Sep 17 00:00:00 2001 From: EllaKaye Date: Thu, 5 Dec 2024 14:15:19 +0000 Subject: [PATCH 10/10] Add publish GHA --- .github/workflows/deploy_bookdown.yml | 55 --------------------------- .github/workflows/publish.yml | 25 ++++++++++++ 2 files changed, 25 insertions(+), 55 deletions(-) delete mode 100644 .github/workflows/deploy_bookdown.yml create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/deploy_bookdown.yml b/.github/workflows/deploy_bookdown.yml deleted file mode 100644 index 5b358d2a..00000000 --- a/.github/workflows/deploy_bookdown.yml +++ /dev/null @@ -1,55 +0,0 @@ -on: - push: - branches: - - main - - -name: renderbook - -jobs: - bookdown: - name: Render-Book - runs-on: macOS-latest - steps: - - uses: actions/checkout@v4 - - uses: r-lib/actions/setup-r@v2 - - uses: r-lib/actions/setup-pandoc@v2 - - uses: r-lib/actions/setup-tinytex@v2 - - name: Install rmarkdown - run: Rscript -e 'install.packages(c("rmarkdown","bookdown"))' - - name: Render HTML - run: Rscript -e 'bookdown::render_book("index.Rmd", "bookdown::gitbook")' - - name: Render PDF - run: Rscript -e 'bookdown::render_book("index.Rmd", "bookdown::pdf_book")' - - name: Render ePub - run: Rscript -e 'bookdown::render_book("index.Rmd", "bookdown::epub_book")' - - uses: actions/upload-artifact@v4 - with: - name: docs - path: docs/ - -# Need to first create an empty gh-pages branch -# see https://pkgdown.r-lib.org/reference/deploy_site_github.html -# and also add secrets for a GH_PAT and EMAIL to the repository -# gh-action from Cecilapp/GitHub-Pages-deploy - checkout-and-deploy: - name: Check-out and deploy - runs-on: ubuntu-latest - needs: bookdown - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Download artifact - uses: actions/download-artifact@v4 - with: - # Artifact name - name: docs # optional - # Destination path - path: docs # optional - - name: Deploy to GitHub Pages - uses: Cecilapp/GitHub-Pages-deploy@v3 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - build_dir: docs/ # "_site/" by default - email: ${{ secrets.EMAIL }} # must be a verified email diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..2d3d5e88 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,25 @@ +on: + workflow_dispatch: + push: + branches: main + +name: Quarto Publish + +jobs: + build-deploy: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + + - name: Render and Publish + uses: quarto-dev/quarto-actions/publish@v2 + with: + target: gh-pages + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file