Deep Linking Overview

unfoldingWord’s suite of content resources are linked together in a very granular manner. Somewhat similar to the concept of deep linking on the internet, our resources are designed such that one resource can link directly to a specific piece of content in another resource. Some of this is enabled by our resource container specification which allows one resource to link deeply into another resource.

Another method that we use for deep linking is our TSV translation notes data format. This allows linking into the word or phrase level of the biblical text. A third method that we use is data mark up inline with the original language resources.

Effectively, there are three methods that we use for deep linking:

  • Resource Container links
  • TSV (tab separated file) links in our Translation Notes resource
  • Inline markup from original language texts to other resources

Each of these is discussed and diagrammed below.

Resource Container Links

Deep Linking Within a Resource

graph LR; subgraph Translation Words A[Abomination Article] click A "https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/kt/abomination.md" B[Adultery Article] click B "https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/kt/adultery.md" A--Resource Container Link-->B end

This sort of linking is common for many resources, especially reference resources which often want to provide a way for the reader to learn more about a related topic.

Deep Linking Between Resources

graph TB; subgraph Translation Words A[Almighty Article] click A "https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/kt/almighty.md" end subgraph Translation Academy B[How to Translate Names Module] click B "https://git.door43.org/unfoldingWord/en_ta/src/branch/master/translate/translate-names/01.md" A--Resource Container Link-->B end

This type of link is less common but incredibly valuable. The benefit is the same as above, the ability to provide more information, but you were no longer constrained to a single resource. This ability makes it possible for any resources to refer to a specific place in any other resource.

Mapping Relationships

graph TB; subgraph Translation Words A[Almighty Article] click A "https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/kt/almighty.md" C[God Article] click A "https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/kt/god.md" D[Lord Article] click A "https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/kt/lord.md" E[Power Article] click A "https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/kt/power.md" A-->C A-->D A-->E D-->C end subgraph Translation Academy B[How to Translate Names Module] click B "https://git.door43.org/unfoldingWord/en_ta/src/branch/master/translate/translate-names/01.md" F[Borrow Words Module] click F "https://git.door43.org/unfoldingWord/en_ta/src/branch/master/translate/translate-transliterate/01.md" A-->B C-->B B-->F end

The presence of of links either within a resource or between resources allows software to create maps of interrelated content. Because links are encoded into the resources themselves and deep linked to other related topics, it is fairly simple for a graphic representation of the related topics to be created. The above graph could be extended if we were to keep linking to all of the topics found in each of the articles, but here I’ve limited it to just one connection for simplicity.

TSV Linking

Original Language Snippets

The primary advantage of the TSV files, and the reason why we pivoted to start using them fairly recently, is that it provides the ability to annotate a specific word or phrase in the original language text. The value of this is that notes can be written against the original language text and then translated and applied in any language of the world.

graph LR; subgraph Translation Notes A[OrigQuote] end subgraph UGNT B[σάρκα μὲν μιαίνουσιν] A--Quotation-->B end

Support Reference Links

A feature of the TSV files for translation notes is that they include a specific column for a support reference. By convention this refers to a translation Academy article. These links are usually found in the notes, but they are pulled out to a separate column for easier processing for software. This also allows a top level category to be assigned to the note itself, even though it may reference other resources in the note.

The entries in the SupportReference column are the method by which the Translation Notes data can be pivoted and looked at topically. This is the underlying principle that translationCore operates on for running checks in its translationNotes tool. For example, all metaphors can be parsed out by looking at entries that have figs-metaphor in their SupportReference field.

graph LR; subgraph Translation Notes A[SupportReference] end subgraph Translation Academy B[Metaphor Module] A--Resource Container Link-->B end

Example Connections

The following line from the Jude Translation Notes resources connects to the UGNT, Translation Academy, and also references the ULT:

Book	Chapter	Verse	ID	SupportReference	OrigQuote	Occurrence	GLQuote	OccurrenceNote
JUD	1	8	ez4l	figs-metaphor	σάρκα μὲν μιαίνουσιν	1	pollute their bodies	This metaphor says that their sin makes their bodies—that is, their actions—unacceptable the way garbage in a stream makes the water undrinkable. (See: [[rc://en/ta/man/translate/figs-metaphor]])
graph TB; subgraph Translation Notes subgraph OrigQuote A[σάρκα μὲν μιαίνουσιν] click A "https://git.door43.org/unfoldingWord/en_tn/src/branch/master/en_tn_66-JUD.tsv#L27" end subgraph SupportReference C[figs-metaphor] click C "https://git.door43.org/unfoldingWord/en_tn/src/branch/master/en_tn_66-JUD.tsv#L27" end end subgraph UGNT B[σάρκα μὲν μιαίνουσιν] click B "https://git.door43.org/unfoldingWord/el-x-koine_ugnt/src/branch/master/66-JUD.usfm#L188-L190" A-->B end subgraph Translation Academy D[Metaphor Module] click D "https://git.door43.org/unfoldingWord/en_ta/src/branch/master/translate/figs-metaphor/01.md" C-->D end

Resource Container Links

As the previous section demonstrated, it is also possible to use resource container links within a particular note in the TSV files. This allows the same sort of flexibility and specificity described under the resource container link section.

Inline Markup

The third way that our resources link to one another is through inline markup in our original language texts. There are three pieces of metadata currently tracked that can link to other resources:

  1. lemma–this can link to a lexicon resource but we currently use for fall back mapping in wordMap when identifying word or phrase pairs.
  2. strong–this links to a Strong’s encoded lexicon or any other resource with Strong’s targets
  3. x-tw–this links to our Translation Words resource.
graph LR; subgraph UGNT A[Word] end subgraph Translation Words B[Article] A--"x-tw'"-->B end subgraph Strong's C[Entry] A--strong-->C end subgraph Lexicon D[Entry] A--lemma-->D end

Example From Jude 1:8

Looking at this line there are three links possible, looking like this:

graph TB; subgraph UGNT A[σάρκα] end subgraph Translation Words B[rc://*/tw/dict/bible/kt/flesh] A--"x-tw'"-->B end subgraph Strong's C[G45610] A--strong-->C end subgraph Lexicon D[σάρξ] A--lemma-->D end

Typo: Should be to be assigned to the note itself

Is this statement prematurely ended? I.e., “is currently… what?”

Thanks @mandolyte, I fixed both of those issues.

@joel Does wordMap use the lemma or the strong field for lemma fallback?

it uses the lemma field for the fallback.

1 Like