How to Prepare tS Translation Notes Projects for Publishing
Posted by: Mark


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.


  • 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 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 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 .

Note: This structure will ultimately be replaced by the newer fomat utilizing .tsv files. The newer format is seen in . 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 script can do this conversion. If you use this script, or any other script found in , 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 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/
  • Verify every http or https URL reference.
  • No references of any kind in note titles.
  • No HTML code, such as comments <!-- -->, <b>, <br>, and &nbsp;

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 .
  • 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’
  • Validate yaml syntax with an online checker, like

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: .

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.

MAST technician job description and what to expect.

A MAST technician will encounter a wide range of issues on a MAST. The nature of the issues will be both technical and social. Having impeccable technical skills will only get you part of the way there. You should also be aware that you will need the so-called “soft...

Post MAST-TSP Workshop

Hello all, As we are developing the materials and support that we all need. Would you please add a post here of those things that you would like to have or need to know where it is? For instance - here are the websites that will be good to remember:...

Installing MAST Apps on a tablet

Here is a video on how I install apps...not just any apps....but MAST specific apps on atablet.  I know....sounds exciting!  Well, actually it is.  The work that translators do on these tablets is life changing.  Along with the video, I have added tablet specs and an...

How to Get Help

John explains the different tools used for technical support for Bible Translation.  Email is probably the best type of support.  Just send a helpdesk ticket to [email protected]   Some...

Changing Server Settings

Here is documentation on how to set the WACS server up in tStudio Android. I’m thinking that this will become a popular question. Server Settings Keep the settings for the server as determined by the program. There is no need to edit any of the settings unless...

Android Install

The following apps are recommended to install and place on the front pane of an Android tablet for written and oral translation projects.  The tech only items should not appear on pane display.

Installing SyncThing on a Windows 10 computer

Follow these simple instructions on installing SyncThing on a Windows 10 machine for MAST data collection. Notes: Install SyncTrazor

How to migrate or clone a repo on door43 to WACS

How to migrate or clone a repo on Door43 to WACS. Compare mirror and non-mirror options.

How to format Translation Notes for publishing (V-MAST)

In V-MAST, translators are given free rein to reformat the content. However, they should not reformat content destined to be published as source text. This article specifies the expected content format. Note that BTT Writer does its own formatting when translating tN,...

How to Prepare a Translation Words Project for Publishing

This article is one in what may be a series of articles describing how to get GL projects ready to publish so that others can benefit from them. This article deals with Translation Words (tW) projects. A tW project consists of about 1000 files, each defining one term,...