AMR/R/translate.R

236 lines
11 KiB
R
Raw Normal View History

2018-11-05 13:20:32 +01:00
# ==================================================================== #
# TITLE #
# Antimicrobial Resistance (AMR) Data Analysis for R #
2018-11-05 13:20:32 +01:00
# #
2019-01-02 23:24:07 +01:00
# SOURCE #
2020-07-08 14:48:06 +02:00
# https://github.com/msberends/AMR #
2018-11-05 13:20:32 +01:00
# #
# LICENCE #
2021-12-23 18:56:28 +01:00
# (c) 2018-2022 Berends MS, Luz CF et al. #
2020-10-08 11:16:03 +02:00
# Developed at the University of Groningen, the Netherlands, in #
# collaboration with non-profit organisations Certe Medical #
# Diagnostics & Advice, and University Medical Center Groningen. #
2018-11-05 13:20:32 +01:00
# #
2019-01-02 23:24:07 +01:00
# This R package is free software; you can freely use and distribute #
# it for both personal and commercial purposes under the terms of the #
# GNU General Public License version 2.0 (GNU GPL-2), as published by #
# the Free Software Foundation. #
# We created this package for both routine data analysis and academic #
# research and it was publicly released in the hope that it will be #
# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY. #
2020-10-08 11:16:03 +02:00
# #
# Visit our website for the full manual and a complete tutorial about #
# how to conduct AMR data analysis: https://msberends.github.io/AMR/ #
2018-11-05 13:20:32 +01:00
# ==================================================================== #
2022-08-19 12:33:14 +02:00
#' Translate Strings from the AMR Package
2018-11-05 13:20:32 +01:00
#'
2020-05-16 13:05:47 +02:00
#' For language-dependent output of AMR functions, like [mo_name()], [mo_gramstain()], [mo_type()] and [ab_name()].
#' @inheritSection lifecycle Stable Lifecycle
2022-08-19 12:33:14 +02:00
#' @param x text to translate
#' @param lang language to choose. Use one of these supported language names or ISO-639-1 codes: `r paste0('"', names(LANGUAGES_SUPPORTED), '" ("' , LANGUAGES_SUPPORTED, '")', collapse = ", ")`.
#' @details The currently `r length(LANGUAGES_SUPPORTED)` supported languages are `r vector_and(names(LANGUAGES_SUPPORTED), quotes = FALSE, sort = FALSE)`. All these languages have translations available for all antimicrobial agents and colloquial microorganism names.
2019-05-10 16:44:59 +02:00
#'
2022-08-19 12:33:14 +02:00
#' Please suggest your own translations [by creating a new issue on our repository](https://github.com/msberends/AMR/issues/new?title=Translations). Strings will be translated to foreign languages if they are defined in [this repository file](https://github.com/msberends/AMR/blob/main/data-raw/translations.tsv). This file will be read by all functions where a translated output can be desired, like all [`mo_*`][mo_property()] functions (such as [mo_name()], [mo_gramstain()], [mo_type()], etc.) and [`ab_*`][ab_property()] functions (such as [ab_name()], [ab_group()], etc.).
2019-05-10 16:44:59 +02:00
#'
#' ## Changing the Default Language
2022-08-19 12:33:14 +02:00
#' The system language will be used at default (as returned by `Sys.getenv("LANG")` or, if `LANG` is not set, [Sys.getlocale("LC_COLLATE")]), if that language is supported. But the language to be used can be overwritten in two ways and will be checked in this order:
2020-09-14 12:21:23 +02:00
#'
2022-08-19 12:33:14 +02:00
#' 1. Setting the R option `AMR_locale`, either by using `set_AMR_locale()` or by running e.g. `options(AMR_locale = "de")`.
#'
#' Note that setting an \R option only works in the same session. Save the command `options(AMR_locale = "(your language)")` to your `.Rprofile` file to apply it for every session.
#' 2. Setting the system variable `LANGUAGE` or `LANG`, e.g. by adding `LANGUAGE="de_DE.utf8"` to your `.Renviron` file in your home directory.
2020-09-14 12:21:23 +02:00
#'
#' Thus, if the R option `AMR_locale` is set, the system variables `LANGUAGE` and `LANG` will be ignored.
#' @inheritSection AMR Read more on Our Website!
2019-05-10 16:44:59 +02:00
#' @rdname translate
#' @name translate
2018-11-05 13:20:32 +01:00
#' @export
2019-05-10 16:44:59 +02:00
#' @examples
2022-08-19 12:33:14 +02:00
#' # Current settings
#' ab_name("Ciprofloxacin")
#' mo_name("Coagulase-negative Staphylococcus")
2019-05-10 16:44:59 +02:00
#'
2022-08-19 12:33:14 +02:00
#' # setting another language
#' set_AMR_locale("Greek")
#' ab_name("Ciprofloxacin")
#' mo_name("Coagulase-negative Staphylococcus")
2021-09-29 12:12:35 +02:00
#'
2022-08-19 12:33:14 +02:00
#' set_AMR_locale("Spanish")
#' ab_name("Ciprofloxacin")
#' mo_name("Coagulase-negative Staphylococcus")
2019-05-10 16:44:59 +02:00
#'
2022-08-19 12:33:14 +02:00
#' reset_AMR_locale()
get_AMR_locale <- function() {
2022-08-19 12:33:14 +02:00
if (!is.null(getOption("AMR_locale", default = NULL))) {
return(validate_language(getOption("AMR_locale"), extra_txt = "set with `options(AMR_locale = ...)`"))
}
2022-08-19 12:33:14 +02:00
lang <- ""
# now check the LANGUAGE system variable - return it if set
if (!identical("", Sys.getenv("LANGUAGE"))) {
lang <- Sys.getenv("LANGUAGE")
}
if (!identical("", Sys.getenv("LANG"))) {
lang <- Sys.getenv("LANG")
}
if (lang == "") {
lang <- Sys.getlocale("LC_COLLATE")
2018-11-05 13:20:32 +01:00
}
2020-05-16 13:05:47 +02:00
2022-08-19 12:33:14 +02:00
lang <- find_language(lang)
if (lang != "en" && interactive() && message_not_thrown_before("get_AMR_locale", entire_session = TRUE)) {
message_("Assuming the ", names(LANGUAGES_SUPPORTED)[LANGUAGES_SUPPORTED == lang],
" language for the AMR package. Change this with `set_AMR_locale()`. ",
"This note will be shown once per session.")
}
2022-08-19 12:33:14 +02:00
lang
2020-09-14 12:21:23 +02:00
}
2022-08-19 12:33:14 +02:00
#' @rdname translate
#' @export
set_AMR_locale <- function(lang) {
lang <- validate_language(lang)
options(AMR_locale = lang)
message_("Using the ", names(LANGUAGES_SUPPORTED)[LANGUAGES_SUPPORTED == lang], " language for the AMR package for this session.")
}
#' @rdname translate
#' @export
reset_AMR_locale <- function() {
options(AMR_locale = NULL)
message_("Language for the AMR package reset to English for this session.")
}
#' @rdname translate
#' @export
translate_AMR <- function(x, language = get_AMR_locale()) {
translate_into_language(x, language = language)
}
validate_language <- function(language, extra_txt = character(0)) {
language.bak <- language
language <- LANGUAGES_SUPPORTED[which(tolower(language) == LANGUAGES_SUPPORTED | tolower(names(LANGUAGES_SUPPORTED)) == tolower(language))][1]
stop_ifnot(language %in% LANGUAGES_SUPPORTED,
"unsupported language for AMR package", extra_txt, ": \"", language.bak, "\". Use one of these language names or ISO-639-1 codes: ",
paste0('"', names(LANGUAGES_SUPPORTED), '" ("' , LANGUAGES_SUPPORTED, '")', collapse = ", "),
call = FALSE)
unname(language)
}
find_language <- function(lang) {
# grepl() with ignore.case = FALSE is 8x faster than %like_case%
if (grepl("^(English|en_|EN_)", lang, ignore.case = FALSE, perl = TRUE)) {
2018-11-12 15:07:43 +01:00
# as first option to optimise speed
2018-11-05 13:20:32 +01:00
"en"
2022-08-19 12:33:14 +02:00
} else if (grepl("^(Chinese|zh_|ZH_)", lang, ignore.case = FALSE, perl = TRUE)) {
"zh"
2021-09-29 12:12:35 +02:00
} else if (grepl("^(Danish|Dansk|da_|DA_)", lang, ignore.case = FALSE, perl = TRUE)) {
"da"
2022-08-19 12:33:14 +02:00
} else if (grepl("^(Dutch|Nederlands|nl_|NL_)", lang, ignore.case = FALSE, perl = TRUE)) {
"nl"
} else if (grepl("^(French|Fran.+ais|fr_|FR_)", lang, ignore.case = FALSE, perl = TRUE)) {
2018-11-05 13:20:32 +01:00
"fr"
2022-08-19 12:33:14 +02:00
} else if (grepl("^(German|Deutsch|de_|DE_)", lang, ignore.case = FALSE, perl = TRUE)) {
"de"
} else if (grepl("^(Greek|el_|EL_)", lang, ignore.case = FALSE, perl = TRUE)) {
"el"
} else if (grepl("^(Italian|Italiano|it_|IT_)", lang, ignore.case = FALSE, perl = TRUE)) {
"it"
} else if (grepl("^(Japanese|ja_|JA_)", lang, ignore.case = FALSE, perl = TRUE)) {
"ja"
} else if (grepl("^(Polish|polsk|pl_|PL_)", lang, ignore.case = FALSE, perl = TRUE)) {
"pl"
} else if (grepl("^(Portuguese|Portugu.+s|pt_|PT_)", lang, ignore.case = FALSE, perl = TRUE)) {
2018-11-05 13:20:32 +01:00
"pt"
2021-12-12 11:07:02 +01:00
} else if (grepl("^(Russian|pycc|ru_|RU_)", lang, ignore.case = FALSE, perl = TRUE)) {
"ru"
2022-08-19 12:33:14 +02:00
} else if (grepl("^(Spanish|Espa.+ol|es_|ES_)", lang, ignore.case = FALSE, perl = TRUE)) {
"es"
} else if (grepl("^(Swedish|Svenskt|sv_|SV_)", lang, ignore.case = FALSE, perl = TRUE)) {
"sv"
2022-08-19 12:33:14 +02:00
} else if (grepl("^(Ukrainian|uk_|UK)", lang, ignore.case = FALSE, perl = TRUE)) {
"uk"
2018-11-12 15:07:43 +01:00
} else {
2018-11-15 12:42:35 +01:00
# other language -> set to English
2018-11-12 15:07:43 +01:00
"en"
2018-11-05 13:20:32 +01:00
}
}
# translate strings based on inst/translations.tsv
2022-08-19 12:33:14 +02:00
translate_into_language <- function(from,
language = get_AMR_locale(),
only_unknown = FALSE,
only_affect_ab_names = FALSE,
only_affect_mo_names = FALSE) {
2020-05-16 13:05:47 +02:00
if (is.null(language)) {
return(from)
}
if (language %in% c("en", "", NA)) {
return(from)
}
df_trans <- TRANSLATIONS # internal data file
from.bak <- from
from_unique <- unique(from)
from_unique_translated <- from_unique
2022-08-19 12:33:14 +02:00
# name of language used
language.bak <- language
language <- LANGUAGES_SUPPORTED[which(tolower(language) == LANGUAGES_SUPPORTED | tolower(names(LANGUAGES_SUPPORTED)) == tolower(language))][1]
stop_ifnot(language %in% LANGUAGES_SUPPORTED,
2022-08-19 12:33:14 +02:00
"unsupported language: \"", language.bak, "\" - use one of these language names or ISO-639-1 codes: ",
paste0('"', names(LANGUAGES_SUPPORTED), '" ("' , LANGUAGES_SUPPORTED, '")', collapse = ", "),
call = FALSE)
# only keep lines where translation is available for this language
df_trans <- df_trans[which(!is.na(df_trans[, language, drop = TRUE])), , drop = FALSE]
2021-05-17 11:26:12 +02:00
# and where the original string is not equal to the string in the target language
df_trans <- df_trans[which(df_trans[, "pattern", drop = TRUE] != df_trans[, language, drop = TRUE]), , drop = FALSE]
if (only_unknown == TRUE) {
2020-07-08 14:48:06 +02:00
df_trans <- subset(df_trans, pattern %like% "unknown")
}
2021-05-17 11:26:12 +02:00
if (only_affect_ab_names == TRUE) {
df_trans <- subset(df_trans, affect_ab_name == TRUE)
}
if (only_affect_mo_names == TRUE) {
2021-02-18 23:23:14 +01:00
df_trans <- subset(df_trans, affect_mo_name == TRUE)
}
2021-05-17 11:26:12 +02:00
if (NROW(df_trans) == 0) {
return(from)
}
# default: case sensitive if value if 'case_sensitive' is missing:
df_trans$case_sensitive[is.na(df_trans$case_sensitive)] <- TRUE
# default: not using regular expressions if 'regular_expr' is missing:
df_trans$regular_expr[is.na(df_trans$regular_expr)] <- FALSE
# check if text to look for is in one of the patterns
2021-04-07 08:37:42 +02:00
any_form_in_patterns <- tryCatch(
any(from_unique %like% paste0("(", paste(gsub(" +\\(.*", "", df_trans$pattern), collapse = "|"), ")")),
error = function(e) {
warning_("Translation not possible. Please open an issue on GitHub (https://github.com/msberends/AMR/issues).")
2021-04-07 08:37:42 +02:00
return(FALSE)
})
if (NROW(df_trans) == 0 | !any_form_in_patterns) {
return(from)
}
lapply(seq_len(nrow(df_trans)),
function(i) from_unique_translated <<- gsub(pattern = df_trans$pattern[i],
replacement = df_trans[i, language, drop = TRUE],
x = from_unique_translated,
2021-04-07 08:37:42 +02:00
ignore.case = !df_trans$case_sensitive[i] & df_trans$regular_expr[i],
fixed = !df_trans$regular_expr[i],
perl = df_trans$regular_expr[i]))
# force UTF-8 for diacritics
from_unique_translated <- enc2utf8(from_unique_translated)
2022-08-19 12:33:14 +02:00
# a kind of left join to get all results back
from_unique_translated[match(from.bak, from_unique)]
}