translate: Interactive Translation Tool for Sumerian Text

Description

Opens an interactive Shiny gadget for translating a single line of Sumerian cuneiform text. The page displays four sections on a single scrollable page: n-gram patterns, context with neighbouring lines, grammar probabilities, and an interactive skeleton with dictionary lookup. When the user clicks “Done”, the function returns a skeleton object with the updated translations.

Usage

translate(x, text = NULL, dic = NULL, mapping = NULL, fill = NULL,
          min_freq = c(6, 4, 2), sentence_prob = 1.0,
          viewer = shiny::paneViewer())

Value

A skeleton object (character vector of class c("skeleton", "character")), generated by calling skeleton with the final bracket string and updated fill data frame. Returns invisible(NULL) if the user closes the window without clicking “Done”.

Arguments

x: A single Sumerian text string (transliteration, sign names, or cuneiform), or an integer line number indexing into text.
text: A character vector containing the full text being translated (one line per element), a file path to load with readLines(), or NULL. Lines may start with numbering like "12)\t..." or "12. ...". Required when x is an integer; optional otherwise. If a single string that is an existing file path, it is loaded automatically.
dic: A dictionary (data.frame), a list of dictionaries, or a character vector of file paths to dictionary files. If file paths are given, each is loaded with read_dictionary. If NULL, the built-in dictionary is loaded via read_dictionary().
mapping: A data frame containing the sign mapping table with columns syllables, name, and cuneiform. If NULL (the default), the package's internal mapping file etcsl_mapping.txt is loaded.
fill: A pre-computed substring info data frame (as from init_substr_info or guess_substr_info). If NULL, it is computed automatically via guess_substr_info.
min_freq: Minimum frequency thresholds passed to ngram_frequencies. A numeric vector where the i-th element is the minimum frequency for n-grams of length i. Default is c(6, 4, 2).
sentence_prob: Probability that a randomly chosen sign is part of a sentence with a verb, passed to prior_probs. Default is 1.0.
viewer: A Shiny viewer function that controls where the gadget window is opened. The default is shiny::paneViewer() which uses the RStudio Viewer pane. Use shiny::browserViewer() to open in the system browser, or shiny::dialogViewer("Translate", width = 842, height = 900) to open a fixed-size dialog in RStudio

Details

The gadget opens in the viewer specified by the viewer parameter (by default a dialog window in RStudio) and displays four sections on a single scrollable page. The first three sections (N-grams, Context, Grammar) can be collapsed individually. A sticky navigation menu at the top allows jumping to each section.

N-gram Patterns: Displays a merged table of n-gram combinations that appear in the current line: n-grams of length 2 or more from the full text (controlled by min_freq), combined with shared n-grams found in neighbouring lines. A “Theme” column marks n-grams shared with the context. Frequencies refer to the full text.
Context: Shows neighbouring lines (up to 2 before and after) with frequent n-grams marked. Only available when text is provided and the line index is known.
Grammar Probabilities: Displays a bar chart of grammar probabilities for each sign in the line, computed via grammar_probs with the given sentence_prob.
Translation: The main interactive section with dictionary selection checkboxes, a bracket input field for editing the skeleton structure, an interactive skeleton display with type and translation fields, and a dictionary lookup panel. Clicking a dictionary row adopts its type and translation into the selected skeleton entry.

When the line contains multiple sentences (separated by dots in the transliteration), skeleton entries belonging to different sentences are displayed with alternating background colours.

The bracket input field allows the user to add or modify brackets (), <>, {} to control the grouping structure of the skeleton. Pressing “Update Skeleton” rebuilds the skeleton display while preserving all translations in the fill data frame.

Examples

Run this code

if (FALSE) {
# Basic usage with a transliterated string
result <- translate("lugal kur-ra-ke4")


# Full example with package data
x <- " ki a. jal2 (e2-kur) ra. gaba jal2. an ki a"

dict_file <- system.file("extdata", "sumer-dictionary.txt", package = "sumer")
text_file <- system.file("extdata", "enki_and_the_world_order.txt", package = "sumer")

result <- translate(x,
                text = text_file,
                dic = dict_file,
                min_freq = c(6, 4, 2),
                sentence_prob = 0.25)
print(result)



# Open in system browser (resizable, survives standby)

x <- 9

result <- translate(x,
                text = text_file,
                dic = dict_file,
                min_freq = c(6, 4, 2),
                sentence_prob = 0.25,
                viewer = shiny::browserViewer())
print(result)

}