Skip to contents

Generate multilingual HTML labels for plant collections

Source: R/arboretum_labels.R
arboretum_labels.Rd

This function generates one standalone HTML label per species for botanical, arboretum, and living plant collections. Each label includes taxonomic information, multilingual species descriptions, browser-based audio playback, interactive distribution maps, optional personal audio recordings, optional personal photos, and institutional or package logos.

The function is designed to be used with data generated by arboretum_data() and phrases generated by arboretum_phrases(). It reads a CSV or Excel file, takes the species descriptions of the selected built-in languages from the full_phrases_* columns (phrases are never generated here, so any manual edit made to them is used as is), creates world and Brazil distribution maps, and saves the resulting HTML files to an output directory.

In addition to the built-in interface languages ("pt", "en", "fr", and "es"), users may supply one extra language through add_lang. This extra language is intended as a flexible accessibility pathway for situations where the package interface does not need to be fully translated, but species labels should still include text and optionally audio in a local, Indigenous, or community language.

When add_lang is supplied and the input data contains non-empty values in the column full_phrases_ADD_LANGUAGE, the function adds that extra language as an additional label text option. In this case, the custom language does not pass through the standard phrase-generation and translation workflow. Instead, the content is taken directly from full_phrases_ADD_LANGUAGE.

When personal audio recordings are available in the expected folder structure, they are embedded in the HTML label and take priority over browser text-to-speech. If no personal recording is available for a given species and language, the label falls back to the browser's speech synthesis engine. When personal photos are available, they are embedded as a slideshow in the species label.

Usage

arboretum_labels(
  data_path = NULL,
  audio_dir = "arboretum_audios",
  photo_dir = "arboretum_photos",
  printed_lang = c("pt", "en", "fr", "es"),
  add_lang = NULL,
  path_to_logo = NULL,
  logo_url = NULL,
  back_to_index = TRUE,
  index_file = "index.html",
  verbose = TRUE,
  dir = "arboretum_labels"
)

Arguments

data_path

Required. Character string giving the path to the input data file. The file must be in CSV or Excel format and is typically generated by arboretum_data() and completed by arboretum_phrases(). It must contain the full_phrases_* columns of every language in printed_lang. Additional columns such as scientificNameAuthorship, plant_uses_EN, plant_uses_PT, plant_uses_ES, plant_uses_FR, free_notes_EN, free_notes_PT, free_notes_ES, free_notes_FR, FFB.url, POWO.url, IUCN.status, botanical_country, introduced_to, FFB.stateProvince, FFB.establishmentMeans, and full_phrases_ADD_LANGUAGE are used when available.

audio_dir

Character string. Directory containing personal audio recordings, usually created with arboretum_audios(). Default is "arboretum_audios". The expected subfolder pattern is FAMILY_Genus_species_LANG, for example FABACEAE_Paubrasilia_echinata_PT. Supported audio file extensions are .mp3, .wav, .m4a, .ogg, .flac and .webm.

photo_dir

Character string. Directory containing personal species photos, usually created with arboretum_photos(). Default is "arboretum_photos". The expected subfolder pattern is FAMILY_Genus_species_photos, for example FABACEAE_Paubrasilia_echinata_photos. Supported image file extensions include .jpg, .jpeg, .png, .gif, .webp, .bmp, and .svg.

printed_lang

Character vector. Language codes to include in the HTML labels. Accepted values are "pt" for Portuguese, "en" for English, "fr" for French, and "es" for Spanish. Default is c("pt", "en", "fr", "es"). The first language in the vector is used as the initial display language.

add_lang

Character string or NULL. Optional code for one additional language to include in the labels, for example "PANARA" or "TUKANO". This argument is intended for cases where users want to include species text and optional personal audio in a community or local language without translating the entire website or minisite interface. When supplied, and when the input data contains non-empty values in the column full_phrases_ADD_LANGUAGE, this extra language is added as an additional text option in the species label. The custom language content is read directly from full_phrases_ADD_LANGUAGE rather than being generated by the standard multilingual phrase builder.

Character string or NULL. Path to an optional logo image to display in the top-right corner of each label. Supported formats are PNG, JPG/JPEG, GIF, SVG, and WebP. If NULL, no custom logo is shown.

logo_url

Character string or NULL. URL to open when the custom logo is clicked. This argument is used only when path_to_logo is supplied. If NULL, the logo is displayed without a hyperlink.

back_to_index

Logical. If TRUE, adds a discrete link below the family name allowing users to return to the minisite index page. Default is TRUE.

index_file

Character string. Relative path to the minisite index page. Default is "index.html". This is usually correct when the species label files and index.html are in the same folder.

verbose

Logical. If TRUE, progress messages are printed to the console. Default is TRUE.

dir

Character string. Output directory where the generated HTML files will be saved. The directory is created if it does not already exist. Default is "arboretum_labels".

Value

Invisibly returns a character vector with the file paths of the generated HTML labels, one file per species. The function is called mainly for its side effects:

  • creates the output directory, if needed;

  • copies non-empty personal audio and photo directories into the output directory;

  • generates one HTML label file per species;

  • downloads and processes geographic data used for distribution maps;

  • removes the temporary WGSRPD folder after label generation.

Details

The function follows five main steps:

  1. Input preparation

    • Validates the output directory and selected languages.

    • Creates the output directory if it does not exist.

    • Reads the input CSV or Excel file using an internal helper function.

  2. Optional media preparation

    • Checks whether the personal audio directory exists and contains files.

    • Checks whether the photo directory exists and contains files.

    • Copies non-empty personal audio and photo directories into the output directory and renames the copied folders with a double-underscore prefix.

    • Ignores empty or missing personal audio and photo directories.

  3. Species phrases

    • Reads the species description of each selected built-in language from the full_phrases_* columns created by arboretum_phrases(). The function stops if a column is missing and warns about species without a stored phrase.

    • When add_lang is supplied and full_phrases_ADD_LANGUAGE contains non-empty text, adds one extra language directly from that column.

    • This extra language bypasses the standard translation and phrase-generation workflow and is intended for flexible community-based accessibility use cases.

    • Adds plant-use and free-note fields to the visible and spoken text when language-specific columns are present and not empty.

  4. Map generation

    • Downloads WGSRPD level-3 geographic data for world distribution maps.

    • Reads Brazilian state boundaries using geobr::read_state().

    • Creates an interactive world map using native and introduced distribution information when available.

    • Creates a Brazil map when FFB.stateProvince contains Brazilian state records.

  5. HTML label generation

    • Creates one HTML file per species.

    • Adds the species name, authorship, family, description text, audio controls, language-switching buttons, distribution maps, source/status icons, package logos, optional custom logo, and optional photo slideshow.

    • Embeds available personal audio files and personal photos as data URIs so the generated HTML labels are self-contained.

    • Uses browser text-to-speech when personal audio is unavailable.

Generated file names follow the pattern:


FAMILY_Genus_species_label.html

For example:


FABACEAE_Paubrasilia_echinata_label.html

Personal audio folders should follow the pattern:


FAMILY_Genus_species_LANG

where LANG is one of PT, EN, FR, ES, or an additional user-defined language code supplied through add_lang.

Personal photo folders should follow the pattern:


FAMILY_Genus_species_photos

Note

  • This function requires an internet connection to download WGSRPD geographic data and to retrieve Brazil state boundaries through geobr.

  • Browser text-to-speech quality depends on the user's browser, operating system, and installed voices.

  • Personal audio recordings take priority over browser text-to-speech when available for a given species and language.

  • Only the first audio file found in a species-language audio folder is used.

  • Photo slideshows are included only when image files are found in the expected species photo folder.

  • The speech rate, pitch, and volume are currently fixed internally in the generated HTML.

  • Missing optional columns are ignored when possible, but missing core columns such as taxonName or family may cause errors.

  • The add_lang argument is intended as a flexible, interim solution for adding one extra language to species labels and associated audio, especially in collaborative work with Indigenous peoples or other local communities where full website translation is not necessary or not yet available.

  • For custom languages added through add_lang, browser text-to-speech may not work reliably unless the user's system provides a compatible voice. Personal recordings are therefore recommended for the extra language whenever possible.

See also

arboretum_data, arboretum_audios, arboretum_photos

Author

Martin Boucknooghe & Domingos Cardoso

Examples

if (FALSE) { # \dontrun{
# Generate labels with default settings and all supported languages
arboretum_labels(
data_path = "arboretum_data/arboretum_data.xlsx"
)

# Generate labels in Portuguese and English only
arboretum_labels(
data_path = "arboretum_data/arboretum_data.xlsx",
printed_lang = c("pt", "en")
)

# Add an institutional logo with a clickable URL
arboretum_labels(
data_path = "arboretum_data/arboretum_data.xlsx",
path_to_logo = "path/to/institution_logo.png",
logo_url = "https://www.institution.org",
dir = "my_arboretum_labels"
)

# Use personal audio recordings and personal photos
arboretum_labels(
data_path = "arboretum_data/arboretum_data.xlsx",
audio_dir = "arboretum_audios",
photo_dir = "arboretum_photos",
printed_lang = c("pt", "en", "fr"),
verbose = TRUE
)

# Generate English-only labels without progress messages
arboretum_labels(
data_path = "arboretum_data/arboretum_data.csv",
printed_lang = "en",
verbose = FALSE
)
} # }