How to Prepare a Translation Words Project for Publishing
Posted by: lversaw

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, with variants, definition, facts, references, translation suggestions, etc. Together, they constitute a basic Bible lexicon. When published, these will help translators make the best possible translation decisions. Here is how to publish on Door43.

Prerequisites

  • The tW files are in markdown format, and named with .md file extension.
  • The tW files are organized in a directory structure with a bible folder at the top level and three folders underneath: ktnames, and other.
  • The reader knows how to copy files between Door43 and a file system on a computer.

tW files uploaded directly from tS will not be in markdown format. In that case, extra conversion steps (outside the scope of this article) are required to achieve these prerequisites.

Verify the .md files, and make corrections

This section represents the main work of preparing a tW project for publication. You should perform as many of these steps as you reasonably can, in advance of submitting the project for publication.

  • Count approximately 1,020 .md files in the three folders.
  • No empty .md files.
  • Each .md file must begin with a valid level 1 <h1> heading. A valid <h1> heading starts with a single hash symbol at the beginning of the first line, followed by a space, followed by the word or words which are the subject of that file.
  • The second line in the file must be blank.
  • The third line must be a valid level 2 <h2> heading. It must start with two hash symbols at the beginning of the line, followed by a space, followed by some word like “Definition”.
  • Headings should not contain any explicit markdown formatting, like bold or italic (**, __, *, or _).
  • The .md file must use UTF-8 character encoding, with no Byte Order Mark (BOM).
  • Blank lines before and efter each <h2> heading.
  • No gratuitous headings. tW doesn’t need any <h3> or higher level headings.
  • Uses asterisks, not any other character, for unordered list items.
  • Asterisks marking list items should be placed at the beginning of a line. Exception: multi-level lists, which are rare in tW.
  • A space character must follow the asterisk marking a list item.
  • Ordered list items begin with a number, followed by a period, followed by a space character.
  • Blank line before the first item in a list.
  • Blank line after the last item in a list – marks the end of the list.
  • References to tA articles are properly formed, for example: [How to Translate Names](rc://plt/ta/man/translate/translate-names)
  • All such references must contain the correct language code (“plt” in the above example).
  • References to other words are properly formed, for example[Gad](../names/gad.md)
  • Verify every http or https URL reference.
  • No references of any kind in headings.
  • No HTML code, such as comments <!-- -->, <b>, <br>, and &nbsp;

There are scripts that can do almost all of the above checks or corrections. See https://github.com/unfoldingWord-dev/tools/tree/develop/usfm 4 . The ones listed below will be the most useful for tW projects. Of course, to use them you must adapt the scripts to your own computing environment.

  • tatw_md2md.py
  • tw-addH2headers.py
  • verifyMd.py

Verify the manifest.yaml file and make corrections

  • 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 possible manifest.json file, 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 Words”.
  • With the exception of the English resources, the publisher field should never say “unfoldingWord”.
  • The projects section should have only one entry, looking like this:

-
categories:
identifier: ‘bible’
path: ‘./bible’
sort: 0
title: ‘translationWords’
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 “tW”. The name may also include other identifying information, such as the checking level. Upload your tW 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 tW 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 1 . 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 toward publication.

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]       https://www.youtube.com/watch?v=mphZwBbiuuU   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 tS Translation Notes Projects for Publishing

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