Register a translator — translator

Register a translator within the traduire package, and use it directly. This will allow your code to access translations via translator_translate (or more concisely t_) without having to pass around a translation object. If called from package code (and assuming a single translator per package) then the name argument can be omitted and will be automatically converted into package:<packagename).

translator_register(resources, ..., name = NULL)

translator_unregister(name = NULL)

translator_translate(..., name = NULL, package = NULL)

t_(..., name = NULL, package = NULL)

translator(name = NULL, package = NULL)

translator_set_language(language, name = NULL, package = NULL)

translator_list()

Arguments

resources: Path to a json file containing translation resources. If given in this way, then on-demand translation loading (via resource_pattern) is disabled unless a currently unexposed i18next option is used.
...: For translator_register, arguments passed to traduire_options to build the translator object. All arguments are accepted. For translator_translate and t_, arguments passed to the $t method of the translator object, being string, data, language etc.
name: Optional name for the translator. This should be used only when not using this interface from a package (e.g., from a shiny application). If using from a package you can omit both name and package, and if interacting with translations from another package you should use the package argument (see below).
package: Optional name for the package to find a translator in. This cannot be provided for translator_register and translator_unregister as these should either be registered by name or the package will be determined automatically.
language: Language to use, passed through to i18n's set_language method

Use in package code

The intention is that this would typically be called from .onLoad, something like:


.onLoad <- function(...) {
  path <- system.file("traduire.json", package = "hello", mustWork = TRUE)
  traduire::translator_register(path, "en")
}

and then used from that package's code as


traduire::t_("key")

The language option for this translator can be changed by


traduire::translator_set_language("es")

Every package's translator object is isolated from every other package, and if the traduire functions are called from your package code, then the correct translator should be found automatically.

If you need to get a translation for another package, you should use package argument, for example:


traduire::t_("key", package = "other")

You can change the language in another package (e.g., using traduire::change_language("en", package = "other")) but should be careful to reset this using the returned reset function.

It is not possible to unregister a translator in another package, or to overwrite one.

Translators provided in other packages will be listed by traduire::translator_list with the prefix package: (e.g., package:other) however, you should not access them directly using name = "package:other".

Examples

path <- system.file("examples/simple.json", package = "traduire")
traduire::translator_register(path, name = "myexample")
traduire::t_("hello", language = "fr", name = "myexample")
#> [1] "bonjour le monde"
"myexample" %in% traduire::translator_list()
#> [1] TRUE
traduire::translator_unregister("myexample")