Resource Container Structure¶
Resource containers (RCs) exist as directories. They may be optionally compressed or packaged so long as the compressed file follows standard naming conventions for the file extension. For example:
- a zipped RC would end in
- a tarred RC would end in
- a tarred+bzip2 RC would end in
A git repository is also a valid way to store RCs.
When naming an RC directory or repository the best practice is to use a combination of the resource and
project identifiers e.g.
If the RC contains more than one project just use the resource identifier with an optional Identifier formatted qualifier
nt is the custom qualifier denoting the New Testament.
RCs have a folder structure like the following:
my_resource_container/ |-.git/ |-.apps/ |-LICENSE.md |-manifest.yaml |-media.yaml |-content/
.git: only exists when the RC is stored as a git repository.
.apps: is where applications can store custom meta data about the RC. See App Meta for more information.
LICENSE.md: contains the appropriate license information for the RC.
manifest.yaml: is the RC Manifest File.
media.yaml: contains definitions of Media that has been generated from the content of the RC and where to find them.
content: contains the project files. The name of this directory is subject to the Manifest File. It is also possible for there to be multiple Projects Directories or be excluded altogether.
The project directory is where all of the translation information exists for a single project within an RC. Files in this directory may contain either meta data or readable text.
content/ |-config.yaml |-toc.yaml |-front/ |-back/
The folders and files illustrated above are reserved. Although not required, when used they must fulfill their roles as defined:
config.yamlcontains meta data for the project at varying levels of granularity as specified in the Container Types.
toc.yamlcontains the Table of Contents.
frontdirectory contains the front matter.
backdirectory contains the back matter.
Furthermore, there are reserved chunk files which may exist in any folder including the reserved front and back folders:
md for the file extension in this example.
You should use a file extension that is appropriate for content in your Container Type.
content/ ... |-front/ | |-title.md | |-sub-title.md | |-intro.md | |-reference.md | |-summary.md ...
Once again, these files are not required but must fulfill their roles as defined:
when in a chapter
title.md- contains the chapter title
sub-title.md- contains the sub title of the chapter
intro.md- contains the introduction to the chapter
reference.md- contains a reference displayed at the end of a chapter
summary.md- contains a summary displayed at the end of a chapter
when in “front”
title.md- contains the resource title
sub-title.md- contains the sub title of the resource
intro.md- contains the introduction to the resource
reference.md- contains a reference displayed at the end of the front matter
summary.md- contains a summary displayed at the end of the front matter
Condensed vs Expanded Form¶
At times content can be structured slightly differently for added convenience. If the container type supports it an RC may use one form or the other or both simultaneously.
All Container Types support the expanded form. This form is most suitable for active translations because collaborators are less likely to interfere with other’s files. And it decouples formatting from structure. For example, here’s a Project Directory that has a chapter 1 folder containing several chunks:
content/ ... |-01/ | |-title.md | |-01.md | ... | |-reference.md |-02/ ...
Most Container Types support a condensed form in which content in each chapter folder is stored in a single file. this form is most suitable for content being delivered as source text:
content/ ... |-01.md |-02.md ...
Where the file
01.md may contain the title, sub-title, intro, chunks, etc. for chapter 1.
Naming Chapters and Chunks¶
When naming folders/files for chapters/chunks we suggest you zero pad the chapter or chunk to match the longest chapter or verse in the given book. Doing this allows files to be sorted correctly when viewed in a web application such as git.door43.org.
A chunk is a range of 1 or more verses.
In Psalms there are 150 chapters. This number contains 3 digits so we zero pad all chapters in Psalms to 3 digits. e.g. chapter 1 turns into
001, chapter 10 turns into
010, chapter 100 turns into
Psalm 119 contains 176 verses. This number contains 3 digits so we zero pad all verses in chapter 176 to 3 digits. e.g. verse 1 turns into
001, verse 10 turns into
010, verse 100 turns into
Another verse example:
Psalm 1 contains 6 verses so we zero pad all verses in chapter 1 to 1 digit. e.g. verse 1 turns into
1, verse 2 turns into
Taking from the examples above we would write the chapter/chunk file stucture for Psalm 119:1 as
119/001.md, while the file structure for Psalm 1:1 would be
Content Sort Order¶
When utilizing content in an RC the order is very important. The content sorting rules are defined as:
- front matter directory
- numeric chapter directories sorted numerically in ascending order
- non-numeric chapter directories sorted alphabetically
- back matter directory
- numeric chunks sorted numerically in ascending order
- non-numeric chunks sorted alphabetically
Table of Contents¶
Chapter directories and chunk files are often named with padded integers.
A side effect of this is the natural file order often represents the appropriate order.
However, you may also indicate the order of chapters and frames by providing a table of contents,
toc.yaml, within the Project Directory.
The table of contents is built with small blocks as shown below. All of the fields in the blocks are optional:
--- title: "My Title" sub-title: "My sub-title" link: "my-link" sections: 
titlea header in the table of contents
sub-titlea sub heading in the table of contents
sectionsallow you to nest more blocks.
linkis the chapter Identifier that should be linked to. Alternatively, you may provide a fully qualified link as defined in Linking.
Here is an example
toc.yaml from translationAcademy.
Generally speaking the title and sub-title fields in this file should be the same as what is found in the subsequently named chunks.
However, the TOC is allowed to deviate as necessary.
--- title: "Table of Contents" sections: - title: "1. Getting Started" sections: - title: "Introduction to the Process Manual" link: process-manual - title: "2. Setting Up a Translation Team" sections: - title: "Setting Up A Translation Team" link: setup-team - title: "3. Translating" sections: - title: "Training Before Translation Begins" link: pretranslation-training - title: "Choosing a Translation Platform" link: platforms - title: "Setting Up translationStudio" link: setup-ts - title: "4. Checking" sections: - title: "Training Before Checking Begins" link: prechecking-training - title: "How to Check" link: required-checking - title: "5. Publishing" sections: - title: "Introduction to Publishing" link: intro-publishing - title: "Source Text Process" link: source-text-process - title: "6. Distributing" sections: - title: "Introduction to Distribution" link: intro-share - title: "How to Share Content" link: share-content