# Getting Started with sumer

## 1. Introduction

The `sumer` package provides tools for translating and analyzing Sumerian cuneiform texts. It converts between different text representations, offers dictionary lookup, and includes an interactive translation tool.

Modern scholars typically work with Sumerian texts in transliterated form – a phonetic rendering in Latin characters. For example, the Sumerian word for king is transliterated as `lugal`. However, translation does not depend on pronunciation. The meaning of a sign depends on the sign itself, not on how it is read aloud. Even when there is reason to believe that words with similar pronunciations have similar meanings, dictionaries can be based solely on the cuneiform characters. The same cuneiform sign can have several different readings (transliterations), but it always has exactly one sign name and one cuneiform character.

    library(sumer)
    #> Type 'browseVignettes("sumer")' to get started.

## 2. Representations of Cuneiform Signs

Each cuneiform sign has three representations:

Representation | Example | Description
--- | --- | ---
Transliteration | `lugal` | Phonetic transcription in lowercase letters
Sign name | `LUGAL` | Canonical name in uppercase letters
Cuneiform | 𒈗 | Unicode character (U+12000 to U+12500)

The package works internally with cuneiform characters and sign names. Transliteration serves as a convenient input method.

Note on display: Cuneiform characters require a font supporting the Unicode Cuneiform block (U+12000–U+12500). In RStudio, the AGG graphics backend should be enabled (Tools > Global Options > General > Graphics > Backend > AGG).

### 2.1 Retrieving sign information

The function `info()` retrieves all available information about a sign or sign sequence:

    info("lugal")
    #> 𒈗    LUGAL   lugal, lillan, rab3, šarrum
    #>
    #> syllables      : lugal
    #> sign names     : LUGAL
    #> cuneiform text : 𒈗

For compound expressions, all contained signs are analyzed:

    info("d-en-lil2")
    #> 𒀭    AN  an, d, diĝir, il3, am6, naggax
    #> 𒂗    EN  en, in4, ru12, uru16
    #> 𒆤    KID ke4, kid, lil2, ge2, gi2
    #>
    #> syllables      : d-en-lil2
    #> sign names     : AN.EN.KID
    #> cuneiform text : 𒀭𒂗𒆤

Each sign (d, en, lil2) is shown with its sign name (AN, EN, KID) and cuneiform character. The `alternatives` column lists all possible readings – for instance, EN can also be read as `ru12` or `uru16`.

### 2.2 Conversion between representations

Two functions convert entire texts:

    # Transliteration -> Cuneiform
    as.cuneiform("lugal-e")
    #> 𒈗𒂊
    as.cuneiform(c("d-en-lil2", "an-ki"))
    #> 𒀭𒂗𒆤
    #> 𒀭𒆠

    # Transliteration -> Sign names
    as.sign_name("lugal-e")
    #> LUGAL.E
    as.sign_name(c("d-en-lil2", "an-ki"))
    #> AN.EN.KID
    #> AN.KI

Within a word, hyphens (`-`) separate syllables; dots (`.`) separate sign names; spaces separate words.

## 3. Dictionary Lookup

### 3.1 Loading a dictionary

The package includes a built-in dictionary:

    dic <- read_dictionary()
    #>  ###---------------------------------------------------------------
    #>  ###                Sumerian Dictionary
    #>  ###
    #>  ### Author:  Robin Wellmann
    #>  ### Year:    2026
    #>  ### Version: 0.5
    #>  ### Watch for Updates: https://founder-hypothesis.com/en/sumerian-mythology/downloads/
    #>  ###---------------------------------------------------------------

The vignette “Translating Sumerian Texts” describes how you can create your own dictionary.

### 3.2 Forward lookup: Sumerian -> English

    look_up("lugal", dic)
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>  Search: lugal
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>
    #>  Cuneiform:   𒈗
    #>  Sign Names:  LUGAL
    #>
    #>  ▶ Translations:
    #>   [16] S      great one with human body {king}
    #>   [ 3] S      kingship
    #>   [ 1] S      great one with human body
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────

The output shows the sign name, cuneiform character, translations with frequency counts and grammatical types, and entries for individual signs and substrings. For compound expressions, all partial combinations are looked up as well:

    look_up("d-suen", dic)
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>  Search: d-suen
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>
    #>  Cuneiform:   𒀭𒂗𒍪
    #>  Sign Names:  AN.EN.ZU
    #>
    #>  ▶ Translations:
    #>   [ 8] S      god of heaven who is a cultural leader with knowledge {god Suen}
    #>   [ 1] S      divine cultural leader with knowledge
    #>
    #>  ▶ Individual Signs / Substrings:
    #>
    #>   AN  𒀭
    #>   [29] S      god of heaven
    #>   [18] ☒S→S   divine S
    #>   [5]  S      sky/heaven
    #>   [1]  A☒→A   A by divine intervention
    #>   [1]  S      divine one
    #>
    #>   EN  𒂗
    #>   [17] S      cultural leader
    #>   [4]  S☒→A   who acts as S
    #>   [1]  S      cultural leadership
    #>
    #>   ZU  𒍪
    #>   [1]  S      knowledge
    #>   [1]  ☒S→A   with knowledge about S
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────

### 3.3 Reverse lookup: English -> Sumerian

To find the Sumerian sign for an English term, use `lang = "en"`:

    look_up("Enki", dic, "en")
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>  Search: Enki
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>
    #>  ▶ Matches for 'Enki':
    #>
    #>   AN.EN.KI  𒀭𒂗𒆠
    #>   [1] S      god of heaven who is the cultural leader of the earth {god Enki}
    #>
    #>   AN.ZA.GUD×KUR.BI.I.A  𒀭𒍝𒄠𒁉𒄿𒀀
    #>   [1] S      divine radiance of the strong invincible one, the raw material of the
    #>              god Enki, the god of heaven who is the cultural leader of the earth
    #>              {Zambija}
    #>
    #>   I.A  𒄿𒀀
    #>   [1] S      life force with transformative power {god Enki}
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────

The reverse lookup searches all translations and displays matching entries with their sign names and cuneiform characters.

## 4. The Type System

Each dictionary entry has a grammatical type in addition to its translation. These types describe the function of a sign in a sentence. Since the same sign can serve different functions depending on context, it may have multiple entries with different types.

### 4.1 Basic types

There are three basic types:

Type | Name | Description | Example
--- | --- | --- | ---
S | Substantive | Noun phrases and substantives | “king”, “Earth”
V | Verb | Verbs and verbal expressions | “create”, “go”
A | Attribute | Modifying clauses | “who is strong”

You can see the different types of a sign with `look_up()`:

    look_up("an", dic)
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>  Search: an
    #> ──────────────────────────────────────────────────────────────────────────────────────────
    #>
    #>  Cuneiform:   𒀭
    #>  Sign Names:  AN
    #>
    #>  ▶ Translations:
    #>   [29] S      god of heaven
    #>   [18] ☒S→S   divine S
    #>   [ 5] S      sky/heaven
    #>   [ 1] A☒→A   A by divine intervention
    #>   [ 1] S      divine one
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────

The sign AN appears both as a noun (S: “sky/heaven”) and as an operator that transforms other expressions – which brings us to the next topic.

### 4.2 Operators

In addition to basic types, there are operators. An operator takes one or two expressions of a certain type as arguments and produces an expression of a (possibly different) type. The notation describes where the arguments stand and what type is produced:

Notation | Alternative notation | Meaning
--- | --- | ---
Sx->V | S☒→V | Takes an S to the left, produces a V
xS->S | ☒S→S | Takes an S to the right, produces an S
Sx->A | S☒→A | Takes an S to the left, produces an A
Sx->S | S☒→S | Takes an S to the left, produces an S
xV->V | ☒V→V | Takes a V to the right, produces a V
Vx->V | V☒→V | Takes a V to the left, produces a V
SSx->V | SS☒→V | Takes two S to the left, produces a V

The `x` marks the position of the operator itself. In `Sx->V`, the argument S stands to the left of the operator; in `xS->S`, the argument stands to the right. Some operators with two arguments (like `SSx->V`) take both arguments from the same side. The symbols `x` and `->` have the alternative Unicode representations `☒` and `→` that may appear in dictionary entries and line files.

In translations, the placeholder S (or V) stands for the argument. For example, an operator `xS->S` with the translation “community of S” means: take the noun to the right of this sign and insert it where the S placeholder stands. For operators with two arguments of the same type, the placeholders are numbered: `S1` and `S2`.

Let us trace through a concrete example. Consider the expression `un-ma-gi` from “Enki and the World Order” (line 16), which consists of three signs:

Syllable | Cuneiform Sign | Type | Translation
--- | --- | --- | ---
un | 𒌧 | ☒S→S | community of S
ma | 𒈠 | S | container
gi | 𒄀 | S☒→S | the permanent S

We build up the noun phrase step by step:

1. 𒈠 is a simple noun (S): “container”.
2. 𒄀 is an operator `S☒→S` that takes the S to its left. It binds 𒈠 and replaces the placeholder: “the permanent container”. The result is again an S.
3. 𒌧 is an operator `☒S→S` that takes the S to its right. It binds the result from step 2: “community of the permanent container”. The result is again an S.

Note that operators with arguments at the right-hand side bind stronger than operators with arguments at the left-hand side. The final noun phrase is: “community of the permanent container” (type S). In this context, “community” refers to the people and “permanent container” refers to the land of Sumer. The expression `un-ma-gi` thus means “the people of Sumer”. In the dictionary, such context-dependent meanings are recorded using the notation “literal meaning {specific meaning}”. The dictionary entry for this expression would be: “community of the permanent container {people of Sumer}”. The literal meaning documents the compositional structure, while the specific meaning in curly braces gives a contextual interpretation.

### 4.3 Verb types

A simple verb (type V) stands on its own – for example, “to be used as a resource”. It combines directly with a subject noun phrase (S + V -> SEN) to form a sentence.

Many Sumerian verbs, however, take a noun phrase as their object. The type Vt describes such a transitive verb: it takes an S as its object and produces a complex intransitive verb (V). The translation contains an S placeholder for the object, for example “to equip S”. The resulting V must then be combined with a subject (S) to form a complete sentence (SEN). `Vt` is a generalization of `Sx->V` that also works correctly when the verb has prefixes or suffixes.

In Sumerian, verbs are often preceded by verb prefixes – signs that modify the verb’s meaning (expressing modality, aspect, or other nuances). A verb prefix has the type `☒V→V`: it takes a verb to its right and produces a modified verb. Since each prefix produces a V, multiple prefixes can chain together. They bind from right to left, wrapping around the core verb like layers. Conversely, a verb suffix has the type `V☒→V` and binds from left to right. Prefixes and suffixes can co-occur.

Consider the verb chain `gan-ig-la` from line 8 of “Enki and the World Order”:

Syllable | Cuneiform Sign | Type | Translation
--- | --- | --- | ---
gan | 𒃶 | ☒V→V | may V
ig | 𒅅 | ☒V→V | V with the task of establishing sustenance of human existence
la | 𒆷 | Vt | to equip S

The verb builds up from the core outward:

    𒃶          𒅅                         𒆷
    ☒V→V         ☒V→V                        Vt
    "may V"      "V with the task ..."        "to equip S"
                  └────────────────────────────┘
                  𒅅(𒆷) = "equip S with the task ..."
       └──────────────────────┘
    𒃶(𒅅(𒆷)) = "may equip S with the task ..."

𒆷 (`Vt`: “to equip S”) is the core verb. 𒅅 (`☒V→V`) wraps it with additional meaning. 𒃶 (`☒V→V`) adds modality. The final composed verb is: “may equip S with the task of establishing sustenance of human existence” (`Vt`). This complex verb still has its S placeholder – it will be filled when the verb meets its object during sentence composition.

### 4.4 Composition rules

When two expressions stand side by side and neither is an operator, they are combined by composition rules:

Left | Right | Result | Translation pattern
--- | --- | --- | ---
S | S | S | “X of/with Y”
S | A | S | “X Y” (juxtaposition)
S | V | SEN | “X Y” (subject + verb, “to” stripped)
SEN | SEN | SEN | “X. Y” (sentences joined with period)

The type SEN stands for a complete sentence. It arises when a noun phrase (S) meets a verb (V). For example, if “separated groups” (S) is followed by “to be created” (V), the composition strips the “to” and produces the sentence “Separated groups be created.” (SEN). This raw composition must then be finished by hand – in this case, adjusting the verb form to produce “Separated groups are created.”

These rules, together with the operator types from the previous sections, are sufficient to translate entire Sumerian sentences from their individual parts. Since in Old Sumerian texts, signs decode phrases rather than syllables, this implies that the Old Sumerian language is actually not a natural language. It is a formal language that can be pronounced in any natural language that is sufficiently complex.

## 5. Text Analysis

### 5.1 N-gram analysis

A good first step when working with a new text is to search for frequently recurring sign combinations (n-grams). Such patterns are valuable clues: if a certain sequence of cuneiform signs appears repeatedly, it is likely a fixed term, a compound word, or an idiomatic expression.

The package includes the example text “Enki and the World Order”:

    path <- system.file("extdata", "project", "enki_and_the_world_order.txt", package = "sumer")
    text <- readLines(path, encoding = "UTF-8")

The function `ngram_frequencies()` finds recurring combinations:

    freq <- ngram_frequencies(text, min_freq = c(6, 4, 2))
    head(freq, 10)
    #>    frequency length          combination
    #> 1          2     20 𒀭𒂗𒆠𒈗𒍪𒀊𒆤𒅎𒃲𒈾𒆳𒆪𒁲𒍣𒉈𒌋𒌋𒌋𒈾𒂊
    #> 2          2     16     𒀭𒂗𒆤𒈗𒆳𒆳𒊏𒊏𒂗𒆤𒆠𒂠𒃶𒈾𒀊𒁺
    #> 3          2     15      𒀊𒈬𒌧𒃻𒀊𒆬𒂵𒀀𒀭𒊮𒁉𒃴𒆓𒀀𒀭
    #> 4          2     15      𒀀𒈾𒀀𒊏𒀭𒇲𒀀𒈾𒀀𒊏𒀊𒈭𒂊𒉈𒂗
    #> 5          3     14       𒂍𒆳𒊑𒂍𒀭𒂗𒆤𒇲𒆤𒃻𒅅𒆷𒉆𒋛
    #> 6          2     14       𒉣𒆠𒆠𒆬𒆠𒆗𒆗𒆷𒀸𒈨𒈤𒋗𒋾𒀀
    #> 7          2     14       𒈥𒌅𒈧𒀲𒊕𒂊𒌋𒌋𒌋𒈬𒉌𒉺𒄸𒁺
    #> 8          2     12         𒆤𒈬𒌧𒁕𒄾𒂗𒆤𒆠𒅗𒉌𒀀𒀭
    #> 9         11     10           𒀭𒂗𒆠𒆤𒍠𒁀𒉆𒈪𒅔𒁺
    #> 10         2     10           𒅆𒅎𒈠𒀭𒁻𒁻𒄀𒌋𒌋𒌋

The `min_freq` parameter controls the minimum frequency for different n-gram lengths. The default value `c(6, 4, 2)` means: single signs must occur at least 6 times, pairs at least 4 times, and all longer combinations at least 2 times.

The analysis works from the longest combinations down to the shortest. When a long combination is identified as frequent, duplicated occurrences are masked so that shorter sub-combinations are not falsely counted as frequent just because they are part of the longer combination.

With `mark_ngrams()`, the identified patterns are marked in the text with curly braces:

    text_marked <- mark_ngrams(text, freq)
    cat(text_marked[1:5], sep = "\n")
    #>
    #> 1    𒂗𒈤𒁲 {𒀭𒆠} 𒉪𒅅𒅎𒋼𒈾
    #> 2     { {𒀀 {𒀀𒀭} 𒂗} 𒆠} 𒄞𒁮𒀀𒊑𒀀𒄠 {𒃲𒂊𒌅𒁕}
    #> 3     {𒊩 {𒅗𒂵} }  {𒆳𒃲 { { {𒀭𒂗} 𒆤} 𒇷} }  {𒆠𒉘}  {𒀭 {𒆬𒂵} }
    #> 4    𒈗𒄑 {𒈩 {𒍪𒀊} }  {𒀀𒆕 {𒀀𒆳𒆳} 𒋫𒅍𒆷}

You can also search for a specific pattern in the annotated text:

    term    <- "IGI.DIB.TU"
    pattern <- mark_ngrams(term, freq)
    pattern
    #> [1] " { {𒅆𒁳} 𒌅} "
    result  <- text_marked[grepl(pattern, text_marked, fixed = TRUE)]
    cat(result, sep = "\n")
    #> 12   𒄋 { {𒅆𒁳} 𒌅} 𒇻𒅆 { { {𒅆𒁳} 𒌅} 𒁕}
    #> 13   𒊾 { {𒅆𒁳} 𒌅} 𒊾𒁇 { { {𒅆𒁳} 𒌅} 𒁕}
    #> 53    {𒀭𒉡𒁶𒄷𒄭} 𒇇 {𒍣⟨ĜA2⟩ { {𒌓𒁺} 𒉌} } 𒃢 {𒍣𒃶 { {𒅆𒁳} 𒌅} }
    #> 54   𒀖𒆰 { {𒌓𒁺} 𒉌} 𒀫 {𒍣𒃶 { {𒅆𒁳} 𒌅} }
    #> 55   𒍚 {𒍣⟨ĜA2⟩ { {𒌓𒁺} 𒉌} } 𒈧 {𒍣𒃶 { {𒅆𒁳} 𒌅} }
    #> 80    { { {𒅆𒁳} 𒌅} 𒁕} 𒌉𒊕 {𒀭 {𒆬𒂵} }  {𒈨𒂗}
    #> 196  𒌣𒍣𒆠𒀭 { {𒅆𒁳} 𒌅} 𒍝𒀭𒁶𒋗𒉡𒋼𒂷
    #> 197   { {𒈗 { {𒅆𒁳} 𒌅} } 𒈽𒍣𒆟𒉈}
    #> 198   { {𒂗 { {𒅆𒁳} 𒌅} } 𒊕𒃞 {𒂷𒂷} }
    #> 258   { {𒀀𒇉} 𒈦𒄘𒃼} 𒄠𒃲𒁶𒊮𒅎𒄾 { {𒅆𒁳} 𒌅} 𒁀 {𒈬𒉌} …
    #> 280  𒃻𒆟𒁕𒉌 { {𒅆𒁳} 𒌅}  {𒉡 {𒌓𒁺} }
    #> 296   {𒉣𒃲} XXX { {𒅆𒁳} 𒌅} …
    #> 298  𒀊𒃻𒄭𒀊𒃻 { {𒅆𒁳} 𒌅} …
    #> 402   {𒈗 { {𒅆𒁳} 𒌅} }  {𒂗 { {𒅆𒁳} 𒌅} } 𒁉 {𒋗𒉌𒀀 { {𒃶𒂗} 𒅅} }
    #> 410   { {𒈗 { {𒅆𒁳} 𒌅} } 𒈽𒍣𒆟𒉈}
    #> 411   { {𒂗 { {𒅆𒁳} 𒌅} } 𒊕𒃞 {𒂷𒂷} } 𒋗𒈾 { {𒃶𒂗} 𒅅}

### 5.2 Grammar probabilities

To understand the structure of a sentence, it is helpful to know which grammatical role each individual sign is likely to play. The function `sign_grammar()` looks up each sign of a string in the dictionary and counts how often it occurs with each grammatical type:

    sg  <- sign_grammar("a-ma-ru ba-ur3 ra", dic)

The raw frequencies can be refined into probabilities using a Bayesian model. First, compute the prior distribution of types across all signs in the dictionary:

    prior <- prior_probs(dic, sentence_prob = 0.25)

The `sentence_prob` parameter corrects a systematic bias: if a dictionary was primarily built from noun phrases (rather than complete sentences), verbs are underrepresented. A value of 0.25 means that an estimated 25% of the dictionary entries come from complete sentences. Verb probabilities are then upweighted accordingly.

Next, `grammar_probs()` computes the posterior probabilities for each sign:

    gp <- grammar_probs(sg, prior, dic)

For signs with many dictionary entries, the observed frequencies dominate; for rare signs, the result falls back to the prior distribution. The position of a sign in the sequence is currently not taken into account for calculating probabilities.

The function `plot_sign_grammar()` presents the results as a stacked bar chart:

    plot_sign_grammar(gp, sign_names = TRUE)

Each bar represents a sign position in the sentence. The colours represent grammatical types: green for nouns (S), red shades for verbs (V) and verb operators, blue shades for attribute operators, orange for adjective-like operators (S☒→S), and grey shades for all other operators. A tall bar in a particular colour indicates that the sign likely has that grammatical function.

The chart can also be saved to a file:

    plot_sign_grammar(gp, output_file = "grammar.png")

### 5.3 Grammatical structure of a cuneiform text

Once you have assigned grammatical types to each sign, the function `grammatical_structure()` shows how the parts are grouped according to the operator binding and composition rules. The output uses typed brackets to indicate the role of each group: `()` for substantives (S), `<>` for verbs (V), `[]` for attributes (A), and `{}` for sentences (SEN).

Consider the expression `mec3-ki-aj2-ga-ce-er ce du`:

    x <- "mec3-ki-aj2-ga-ce-er-ce-du"
    x <- paste0(info(x)$reading, collapse = "-")
    x
    #> [1] "meš3-ki-aĝ2-ga-še-er-še-du"
    expr <- split_sumerian(x)$signs
    type <- c("S", "S", "Sx->A", "xS->A", "S", "Sx->S", "S", "Sx->V")

    grammatical_structure(x, type, expr)
    #> {(((meš3)[(ki)aĝ2])[ga((še)er)])<(še)du>}

The following figure shows the same result with colour coding:

The figure shows that the sentence has the typical structure of an Old Sumerian sentence with the subject (mec3) at its beginning, followed by some specifications of the subject (here in square brackets), followed by the object (ce), and the verb (du) that absorbs the object. This example demonstrates that many Sumerian proper names are self-explanatory. The term “mec3-ki-aj2-ga-ce-er” stands for the proper name “Meskiagasher”, but can also be read as a noun phrase.

This visualization makes the grammatical structure explicit and can help verify that the type assignments produce a sensible grouping.

## 6. Interactive Translation with `translate()`

The function `translate()` opens an interactive Shiny gadget for translating Sumerian text. To demonstrate, we use a fragment from line 16 of “Enki and the World Order”:

    x <- as.cuneiform("cag4-kalam-ma-gi-hal. hal-la-gin7.")
    result <- translate(x)

This expression contains eight cuneiform signs. Our task is to assign each sign a grammatical type and translation, and then compose them into coherent English sentences.

### 6.1 Recognizing sentence boundaries

The input actually contains two sentences. You must recognize sentence boundaries yourself – they are not detected automatically. In general, sentence boundaries follow directly after verbs.

A striking feature of this Old Sumerian text is that duplicated signs often mark sentence boundaries: the left occurrence functions as a verb at the end of one sentence, while the right occurrence functions as a noun at the beginning of the next sentence. In our example, the sign HAL (𒄬) appears twice. The first HAL is a verb (Vt: “to split S into separate groups”) ending the first sentence, while the second HAL is a noun (S: “separated groups”) beginning the second sentence.

The two sentences are:

1. `cag4-kalam-ma-gi-hal` (𒊮𒌧𒈠𒄀𒄬): “The central administration splits the people of Sumer into separate groups.”
2. `hal-la-gin7` (𒄬𒆷𒁶): “Places for the separated groups are created.”

### 6.2 Structure of the translate gadget

When `translate()` opens, you see a scrollable page with the following sections. The gadget is described in more detail in the vignette “Translating Sumerian Texts”.

- N-gram patterns – Frequent sign combinations from the text that appear in the current line. This section is only available when used together with a full text.
- Sign combination suggestions – Sign combinations from the current line for which a dictionary offers a translation.
- Context – Neighbouring lines with frequent n-grams marked. This section is only available when used together with a full text.
- Grammar probabilities – A bar chart showing the likelihood of each grammatical type for each sign (see Section 5.2).
- Translation – The main interactive section, containing:
  - A bracket input field with an “Update Skeleton” button for defining the sentence structure (see below).
  - An interactive skeleton with input fields for type and translation. Each entry has a green lookup button and a brown compose button.
  - A dictionary panel that displays lookup results when the green button is clicked.

### 6.3 Looking up and adopting dictionary entries

When the gadget opens, each sign is pre-filled with its most frequent translation from the dictionary. These suggestions are not always correct – they are simply the entries with the highest count.

Consider the sign `gi=GI=𒄀` in our example. The automatic suggestion may show a noun entry (S) if that is the most frequent type for 𒄀 in the dictionary. However, in this context, 𒄀 functions as an adjective operator `S☒→S` meaning “permanent S”.

To correct this:

1. Click the green arrow button next to the 𒄀 entry. This opens the dictionary panel below, showing all entries for 𒄀 with their counts and types.
2. Find the correct entry – in this case, `S☒→S`: “permanent S”.
3. Click the dictionary row to adopt its type and translation into the skeleton.

If you use multiple dictionaries, the first one has priority for the automatic suggestions. All dictionaries are displayed in the lookup panel, so you can choose from any of them.

### 6.4 Defining structure with brackets

In the bracket input field (next to the “Update Skeleton” button), you can control how the skeleton is structured by inserting brackets:

Round brackets `( )` group signs into a compound expression. The skeleton will show an entry for the group in addition to entries for its individual signs. Hence, the brackets tell the tool that these signs form a coherent phrase and adds a line to the skeleton where its translation can be entered.

Angle brackets `< >` mark a fixed term (typically a proper name). No individual entries are generated for the signs inside. For instance, `<d-en-ki>` would be treated as a single unit “Enki” without breaking it into AN, EN, KI.

Curly braces `{ }` mark operator arguments. In most cases this is not necessary, because operators and their arguments are detected automatically. Only when the automatic detection fails – for instance in ambiguous groupings – do you need to specify operator arguments explicitly with curly braces.

After editing the brackets, click “Update Skeleton” to rebuild the template. All previously entered translations are preserved.

### 6.5 Composing entries with the compose button

Once you have assigned types and translations to the individual signs of a group, you can click the brown compose button (𒃻) next to the parent entry. This automatically combines the children into a composed translation, applying the operator and composition rules described in Section 4.

For example, after filling in the three children of `(un-ma-gi)`:

Syllable | Cuneiform Sign | Type | Translation
--- | --- | --- | ---
un | 𒌧 | ☒S→S | community of S
ma | 𒈠 | S | container
gi | 𒄀 | S☒→S | the permanent S

clicking the compose button on the parent entry produces: type S, translation “community of the permanent container”.

The composed translation often needs manual finishing. In this case, you would edit the translation to add the specific meaning: “community of the permanent container {people of Sumer}”. Other common adjustments include adding articles or conjugating verbs. The compose button provides a starting point that you then refine.

### 6.6 Result and next steps

When you click “Done”, `translate()` returns a `skeleton` object – a character vector containing the completed translation in pipe format. This can be saved as a text file:

    result <- translate(x)
    writeLines(result, "my_translation.txt")

The saved file serves as input for building a custom dictionary (see Vignette 2).

A completed translation for our example looks like this:

    Structure: (𒊮(𒌧𒈠𒄀)𒄬). (𒄬𒆷𒁶).

    |cag4-kalam-ma-gi-hal-hal-la-gin7: SEN: The central administration splits
      the people of Sumer into separate groups. Places for the separated
      groups are created.

    |cag4-kalam-ma-gi-hal=ŠA3.UN.MA.GI.HAL: SEN: The central administration
      splits the people of Sumer into separate groups.
    |   cag4=ŠA3=𒊮: S: center {the central administration}
    |   kalam-ma-gi=UN.MA.GI=𒌧𒈠𒄀: S: community of the permanent container {people of Sumer}
    |       kalam=UN=𒌧: ☒S→S: community of S
    |       ma=MA=𒈠: S: container
    |       gi=GI=𒄀: S☒→S: the permanent S
    |   hal=HAL=𒄬: Vt: to split S into separate groups

    |hal-la-gin7=HAL.LA.DIM2=𒄬𒆷𒁶: SEN: Places for the separated groups
      are created.
    |   hal=HAL=𒄬: S: separated groups
    |   la=LA=𒆷: S☒→S: place for S
    |   gin7=DIM2=𒁶: V: to be created

Each line starting with `|` is a dictionary entry. The indentation reflects the hierarchical structure: the overall sentence at the top, word groups below, and individual signs at the deepest level.

Learning by example. The package includes an example project with lines 1–31 of “Enki and the World Order” already translated. You can open any of these lines to study the translations and learn how the type system works in practice:

    path <- system.file("extdata", package = "sumer")

    file.copy(
      from = file.path(path, "project"),
      to   = tempdir(),
      recursive = TRUE
    )

    ctx <- translation_context(
      line_folder   = file.path(tempdir(), "project/lines"),
      text          = file.path(tempdir(), "project/enki_and_the_world_order.txt"),
      dic           = file.path(path, "sumer-dictionary.txt"),
      sentence_prob = 0.25
    )

    # Open line 16 to see the full translation of our example
    translate_line(16, ctx)

The second vignette (“Translating Sumerian Texts”) describes the complete workflow for translating a document line by line and building a dictionary from the results.