diff --git a/booknews.Rmd b/booknews.Rmd index ef5190610..63e522955 100644 --- a/booknews.Rmd +++ b/booknews.Rmd @@ -2,6 +2,8 @@ ## dev version +- 2025-07-11, add mentions of tools useful for translation and localization (#812). + - 2025-07-09, add a mention of ROR IDs (#909). - 2025-07-09, remove the upper-case from the NEWS.md template and update the real example link. (#896) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 6d6487ab2..9e334ca00 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -63,6 +63,8 @@ We recommend you to use the [`codemetar` package](https://github.com/ropensci/co - Provide a way for users to opt out of verbosity, preferably at the package level: make message creation dependent on an environment variable or option (like ["usethis.quiet"](https://usethis.r-lib.org/reference/ui.html?q=usethis.quiet#silencing-output) in the usethis package), rather than on a function parameter. The control of messages could be on several levels ("none", "inform", "debug") rather than logical (no messages at all / all messages). Control of verbosity is useful for end users but also in tests. More interesting comments can be found in an [issue of the tidyverse design guide](https://github.com/tidyverse/design/issues/42). +- You can provide translations for your package's messages. The [potools](https://michaelchirico.github.io/potools/) R package can help you with that task. + ### Interactive/Graphical Interfaces {#interactive-graphical-interfaces} If providing a graphical user interface (GUI) (such as a Shiny app), to facilitate workflow, include a mechanism to automatically reproduce steps taken in the GUI. This could include auto-generation of code to reproduce the same outcomes, the output of intermediate values produced in the interactive tool, or simply clear and well-documented mapping between GUI actions and scripted functions. (See also ["Testing"](#testing) below.) @@ -256,6 +258,8 @@ f <- function(a = TRUE) { - Starting from roxygen2 version 7.0.0, `R6` classes are officially supported. See the [roxygen2 docs](https://roxygen2.r-lib.org/articles/rd-other.html#r6) for details on how to document `R6` classes. +- There is no support for providing manual pages in different languages yet, but some interesting progress in the [rhelpi18n R package](https://github.com/eliocamp/rhelpi18n). + ### URLs in documentation {#ur-ls-in-documentation} This subsection is particularly relevant to authors wishing to submit their package to CRAN. @@ -277,6 +281,12 @@ You only need to worry about automatic deployment of your website until approval Before submission and before transfer, you could use the [approach documented by `pkgdown`](https://pkgdown.r-lib.org/reference/deploy_site_github.html) or the [`tic` package](https://docs.ropensci.org/tic/) for automatic deployment of the package's website. This would save you the hassle of running (and remembering to run) `pkgdown::build_site()` yourself every time the site needs to be updated. First refer to our [chapter on continuous integration](#ci) if you're not familiar with continuous integration. In any case, do not forget to update all occurrences of the website URL after transfer to the ropensci organization. +### Language + +If your package's documentation is written in a language other than English (but supported by the rOpenSci software peer-review system), you can declare that language for your pkgdown website to be [localized](https://pkgdown.r-lib.org/articles/translations.html). + +It is [not yet possible to get a multilingual pkgdown website](https://github.com/r-lib/pkgdown/issues/2258) out of the box. + ### Grouping functions in the reference {#function-grouping} When your package has many functions, use grouping in the reference, which you can do more or less automatically. diff --git a/pkg_building.es.Rmd b/pkg_building.es.Rmd index e3bb2b9dc..3e59f109f 100644 --- a/pkg_building.es.Rmd +++ b/pkg_building.es.Rmd @@ -65,6 +65,8 @@ artículo](https://blog.r-hub.io/2023/11/30/cliff-notes-about-cli/). - Proporciona una forma para suprimir la verbosidad, preferiblemente a nivel de paquete: haz que la creación de mensajes dependa de una variable u opción de entorno (como ["usethis.quiet"](https://usethis.r-lib.org/reference/ui.html?q=usethis.quiet#silencing-output) en el paquete usethis), en lugar de en un parámetro de la función. El control de los mensajes podría ser a varios niveles ("ninguno, "informar", "depurar") en lugar de lógico (ningún mensaje / todos los mensajes). El control de la verbosidad es útil para usuarios/as finales, pero también en las pruebas. Puedes encontrar más comentarios interesantes en [este issue de la guía de diseño de tidyverse](https://github.com/tidyverse/design/issues/42). +- Puedes proporcionar traducciones para los mensajes de tu paquete. El paquete R [potools](https://michaelchirico.github.io/potools/) puede ayudarte con esa tarea. + ### Interfaces interactivas o gráficas {#interactive-graphical-interfaces} Si proporcionas una interfaz gráfica de usuario (GUI) (como una aplicación Shiny), para facilitar el flujo de trabajo incluye un mecanismo para reproducir automáticamente los pasos realizados en la GUI. @@ -284,6 +286,8 @@ f <- function(a = TRUE) { - A partir de la versión 7.0.0 de roxygen2, las clases `R6` son oficialmente compatibles. Consulta la [documentación de roxygen2](https://roxygen2.r-lib.org/articles/rd-other.html#r6) para saber cómo documentar las clases `R6`. +- Todavía no hay soporte para proporcionar páginas de manual en diferentes idiomas, pero se han producido avances interesantes en el paquete R [rhelpi18n](https://github.com/eliocamp/rhelpi18n). + ### URLs en la documentación {#ur-ls-in-documentation} Esta subsección es especialmente relevante para quienes deseen enviar su paquete a CRAN. @@ -314,6 +318,13 @@ Esto te ahorrará el trabajo de ejecutar (y acordarte de ejecutar) `pkgdown::bui Consulta nuestro [capítulo sobre integración continua](#ci) si ésto no te resulta familiar. En cualquier caso, no olvides actualizar la URL del sitio web en todos los lados donde aparezca después de hacer la transferencia a la organización ropensci. + +### Idioma + +Si la documentación de tu paquete está escrita en un idioma distinto del inglés (pero compatible con el sistema de revisión por pares del software rOpenSci), puedes declarar ese idioma para que el sitio web pkgdown se [localice](https://pkgdown.r-lib.org/articles/translations.html). + +Todavía no es posible obtener un sitio web pkgdown multilingüe listo para usar (https://github.com/r-lib/pkgdown/issues/2258). + ### Agrupar funciones en el índice {#function-grouping} Cuando tu paquete tenga muchas funciones, es conveniente que aparezcan agrupadas en el índice de la documentación, lo cual se puede hacer de forma más o menos automática.