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 .zip,
a tarred RC would end in .tar,
a tarred+bzip2 RC would end in .tar.bz2

A git repository is also a valid way to store RCs.

Note

When naming an RC directory or repository the best practice is to use a combination of the resource and project identifiers e.g. en-ulb-gen. If the RC contains more than one project just use the resource identifier with an optional Identifier formatted qualifier e.g. en-ulb-nt where nt is the custom qualifier denoting the New Testament.

Directory Structure¶

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.

Project Directory¶

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.yaml contains meta data for the project at varying levels of granularity as specified in the Container Types.
toc.yaml contains the Table of Contents.
front directory contains the front matter.
back directory contains the back matter.

Furthermore, there are reserved chunk files which may exist in any folder including the reserved front and back folders:

Note

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

Expanded

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

Condensed

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.

Note

A chunk is a range of 1 or more verses.

Chapter example: 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 100 etc.

Verse example: 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 100 etc.

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

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 001/1.md.

Content Sort Order¶

When utilizing content in an RC the order is very important. The content sorting rules are defined as:

Chapters

front matter directory
numeric chapter directories sorted numerically in ascending order
non-numeric chapter directories sorted alphabetically
back matter directory

Chunks

title
sub-title
intro
numeric chunks sorted numerically in ascending order
non-numeric chunks sorted alphabetically
reference
summary

Config¶

The config.yaml file contains information specific to each RC type. If a particular RC type does not need this file it may be excluded.

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: []

title a header in the table of contents
sub-title a sub heading in the table of contents
sections allow you to nest more blocks.
link is 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