Skip to contents

Label languages

Source: vignettes/labels.rmd
labels.rmd

Overview

Observation.org exports often contain coded values for categorical fields (e.g., A, J, M for validation or sex). The locale argument in obs_read() simplifies your workflow by automatically translating these codes into human-readable labels in your preferred language.

This vignette explains how language handling works, what remains standardised, and how to manage language dictionaries.

The Locale Contract: What Changes and What Stays

When you specify a locale, obsR guarantees a consistent structure:

  1. Column names are always in English (e.g., validation, sex, life_stage).
  2. Code columns (ending in _code) always retain the original Observation.org codes (e.g., A, J, M, F, U).
  3. Readable columns contain the translated labels based on the chosen locale.

This design ensures that your analysis scripts remain robust and language-independent, while your outputs and plots are presented in the correct language for your audience.

You can load the same dataset multiple times in a single session with different locales:

# Load with English labels (default)
obs_en <- obs_read(db, locale = "en")

# Load with Spanish labels
obs_es <- obs_read(db, locale = "es")

# The column names and codes remain identical
identical(names(obs_en), names(obs_es))
#> [1] TRUE
identical(obs_en$validation_code, obs_es$validation_code)
#> [1] TRUE

# Only the readable labels change
unique(obs_en$validation)
#> [1] "unknown"                         "accepted (automatic validation)"
#> [3] "accepted (with evidence)"        "accepted (plausible)"           
#> [5] "cannot be validated (yet)"
unique(obs_es$validation)
#> [1] "sin evaluar"                      "aceptada (validación automática)"
#> [3] "aceptada (con pruebas)"           "aceptada (plausible)"            
#> [5] "no se puede validar (aún)"

Important: Species Common Names

The locale argument does not translate species common names. Common names remain exactly as they appear in the original export file (e.g., House Sparrow in an English export, or Gorrión común in a Spanish export).

To ensure your filters work reliably regardless of the export’s origin language, always filter by scientific_name:

# This works reliably across all exports
nrow(obs_read(obs_example_db("es"), species = "Passer domesticus"))
#> [1] 1113

# This may fail if the export language does not match the filter string
nrow(obs_read(obs_example_db("es"), species = "House Sparrow")) # Returns 0
#> Warning: ✖ No observations matched these filters.
#> ℹ Check the spelling of `species` ("House Sparrow"), or call `obs_species()` to
#>   look up names and Observation.org IDs.
#> [1] 0

File Formats: CSV and Excel

The locale argument behaves identically for CSV and Excel files. Observation.org exports these formats with English headers, but the cell values may reflect the language of the user who performed the export. obsR detects the codes and applies the requested locale relabelling seamlessly.

csv_es <- obs_read(obs_example_csv("es"), locale = "en")
head(csv_es$validation)
#> [1] "unknown"                         "accepted (automatic validation)"
#> [3] "unknown"                         "unknown"                        
#> [5] "unknown"                         "accepted (automatic validation)"

Managing Language Dictionaries

Bundled Languages (Offline)

The package ships with built-in dictionaries for English (en), Spanish (es), Dutch (nl), French (fr), and German (de). These are available immediately and require no internet connection.

Additional Languages (Cached)

If you request a locale that is not bundled (e.g., Portuguese pt or Italian it), obsR will fetch the dictionary from the Observation.org API the first time it is needed.

This dictionary is then stored in your local R user cache (tools::R_user_dir("obsR", "cache")). Subsequent calls for that language will use the cached version and work entirely offline. If you are offline and request an uncached language, obsR will issue a warning and safely fall back to English.

# First call: fetches from API and caches
obs_pt <- obs_read(db, locale = "pt")

# Subsequent calls: uses local cache (works offline)
obs_pt <- obs_read(db, locale = "pt")

Updating Dictionaries

Observation.org occasionally updates its terminology. You can refresh all cached dictionaries or fetch specific new ones using obs_update_dictionaries(). Existing cached locales are preserved and updated.

# Update all cached dictionaries
obs_update_dictionaries()

# Fetch and cache a specific new language
obs_update_dictionaries("pt")

(Note: Spatial filtering is covered in a separate vignette: vignette("spatial-filters")).