Note:

This article is one in a series of articles describing how to get a GL project ready to publish so that others can benefit from it. This article deals with Translation Notes (tN) projects created in translationStudio. A complete Bible tN project consists of thousands of markdown files. Each file contains exegetical notes for a single verse or a chunk (several verses). When published, these notes help OL translators make the best possible translation decisions. Here is how to publish on Door43.

Prerequisites

• The notes have been translated in tS and checked to level 3.
• The reader knows how to copy files between Door43 and a file system on a computer.

Upload to Door43

If you haven’t already, upload your project from tS to Door43. The uploaded data will be mainly .txt files with UTF-8 character encoding and JSON content. The .txt files reside in chapter folders corresponding to the chapters of a specific Bible book. Each .txt file contains a JSON representation of one or more notes for a single verse or chunk. The uploaded data also contains:

• One LICENSE.md file per project (Bible book).
• One manifest.json file per project (Bible book).

Convert to Markdown

Copy the entire collection of tN files to a desktop or laptop computer for processing. I do this by using git clone* commands. For example,

git clone https://git.door43.org/maja.seguin/hr_2co_tn.git 1

The conversion process will do a one-for-one conversion of each .txt file to a corresponding .md file in a parallel file structure under the target directory. However the book folders in the target directory must be named with standard USFM, 3-character Bible book abbreviations. The overall folder structure and format must look like that found in https://git.door43.org/WycliffeAssociates/en_tn .

Note: This structure will ultimately be replaced by the newer fomat utilizing .tsv files. The newer format is seen in https://git.door43.org/Door43-Catalog/en_tn . The older format, using .md files, is still supported for publishing Gateway language tN in tS.

Each note within the .txt file consists of a “title” and a “body”. Here is an example:

[
{
“title”: “Zbog onoga što je Bog učinio”,
“body”: “Ovo se odnosi na Kristovo djelo na križu.”
},
{
“title”: “nas… naša”,
“body”: “Ove se riječi odnose na Pavla, one s njim i Korinćane.”
}
]

Each “title” in the .txt file is converted to a markdown heading and each “body” to a paragraph.

# Zbog onoga što je Bog učinio

Ovo se odnosi na Kristovo djelo na križu.

# nas… naša

Ove se riječi odnose na Pavla, one s njim i Korinćane.

The tntq_txt2md.py script can do this conversion. If you use this script, or any other script found in https://github.com/unfoldingWord-dev/tools/tree/develop/usfm , you will first have to adapt it to your computing environment. Besides converting the “title” and “body” of each note, this script performs the following functions:

• Reads manifest.json or parses directory names to get the book IDs.
• Standardizes the names of book folders in the target folder.
• Repairs links of this form [[:en:…]].
• Generates a projects.yaml file whose content may be copied into the projects section of the final manifest.yaml file. (See below.)
• Generates a translators.txt file listing unique translator names gleaned from all the manifest.json files that were processed.
• Also writes into translators.txt a list of the source version(s) from which the notes were translated. This information also comes from the manifest.json files.

Verify the .md files, and make corrections

You should perform as many of these steps as you reasonably can, before requesting publication of the tN project.

• Delete empty .md files.
• The .md file must use UTF-8 character encoding, with no Byte Order Mark (BOM).
• Each .md file must begin with a valid level 1<h1> heading, which means a single hash symbol at the beginning of the first line, followed by a space, followed by the note title.
• Blank line after the first heading.
• Blank lines before and after every other heading in the file.
• A plain text paragraph follows each heading (note title). No lists, headings, nor special formats are wanted.
• References to tA articles are properly formed.
  • Example: “[[rc://hr/ta/man/translate/figs-metaphor]]”
  • All such references must contain the correct language code (“hr” in the example).
  • The tntq_expand_ta_refs.py script expands commonly abbreviated references like “figs_metaphor” to their proper form, as above.
• References to notes in other verses are valid and properly formed, for example: [Luka 17:20](../17/20.md)
• Verify every http or https URL reference.
• No references of any kind in note titles.
• No HTML code, such as comments <!-- -->, <b>, <br>, and  

Create a manifest.yaml file for the tN project

• Borrow a known good manifest.yaml file from another project as a template, but review every line in it.
• Follow the specifications in https://resource-container.readthedocs.io/en/latest/manifest.html .
• Must use UTF-8 character encoding, with no BOM.
• Copy contributor names from the manifest.json files (or translators.txt), and any other source of names that you have.
• Ensure quotes around version number strings.
• Update the issued and modified dates when any content changes.
• Modify only the modified date if just metadata (manifest) changes. If it is just a cosmetic change of no value to end users, do not even modify the modified date.
• Increment the version string whenever the issued date changes.
• The language|title should be localized if possible.
• The subject field must say “Translation Notes”.
• With the exception of the English resources, the publisher field should not say “unfoldingWord”.
• The projects section should have one entry for each Bible book having notes, for example:

• categories:
  identifier: ‘neh’
  path: ‘./neh’
  sort: 16
  title: ‘Nehemiah translationNotes’
  versification:

• Validate yaml syntax with an online checker, like yamllint.com.

Upload to Door43

Create a repository in Door43.
The repository name should include the language code, an underscore, and “tN”. The name may also include other identifying information, such as the checking level. Upload your tN directory structure and files to this repository.

As a final verification step, check the rendering on Door43 by using the Preview button on the repository where you stored the tN project. Look for general appearance, indexing, and read the warnings that were generated. Address whatever doesn’t look right.

Submit a Source Text Request (STR)

Notify the UnfoldingWord team to publish the material by creating a Source Text Request (STR) form: https://git.door43.org/unfoldingWord/SourceTextRequestForm/issues/new .

Once your form is submitted, the unfoldingWord team will verify the license release forms, and will perform all the checks and corrections described above. Any issues requiring translator intervention will be noted in the STR, and will block publication until resolved. Check back often on your STRs to monitor their progress.