Skip to content

Add root and translation content to Bilara

Jump to bottom
Blake Walsh edited this page Apr 20, 2021 · 1 revision

Adding Root Content

In essence root content is content which isn't created in Bilara, and should be added to /root/

As a general rule the folder structure should look this:

/root/pli/ms/

Where pli is the language and ms is the edition. The language has special meaning to the app and is essential - if the language is poorly defined "misc" may be used as the language "code". The edition is merely organizational in nature and is not essential.

Root files should be added to the unpublished branch and can also be added to the published branch, in any case it is only the contents of the unpublished branch that Bilara cares about.

After adding new files to the unpublished branch on Github, the Bilara server should automatically recognize them and make them available as translation sources if applicable.

Adding translations

A translation can be added in one of two ways.

_project.json

The first way which is suitable when there is no existing translation is to simply add an entry to _project.json in the unpublished branch, as usual Bilara cares little for the content of the published branch.

A new entry will look something like this:

"klingon_dn_translation": {
  "name": "Klingon Translation of Digha Nikaya",
  "root_path": "root/pli/ms/sutta/dn",
  "translation_path": "translation/tlh/worf/sutta/dn",
  "translation_muids": "translation-tlh-worf",
  "collaborator": [
    {
      "author_github_handle": "worf"
    }
  ]
}

Take care with commas and other syntax, it's best to use a JSON syntax checker before committing to ensure the JSON file is legal. As an essential file, if _project.json is not legal JSON the Bilara server will violently explode.

The fields should generally be self-explanatory.

  • The "key", "klingon_dn_translation" in this case, does not have to fit any particular format and merely needs to be unique.
  • The root_path should point to a folder under /root, at least to the depth of a language.
  • The translation_path points to where translation files will be created, respecting the subfolders that exist under the root_path, the language is essential but a name or edition is not essential and is merely for organizational purposes.
  • The translation_muids determines the suffix of the file, i.e. dn1_translation-tlh-worf, this suffix must start with "translation-{language}", any additional parts are merely for organizational purposes.
  • The collaborator is a JSON list which defines by the github user handle who is allowed to translate (in the future additional permissions may be defined here).

Once _project.json has been modified within the unpublished branch on Github, the bilara server should automatically reflect the changes, making the new translations available.

A brief explanation of how _project.json works

When an entry is added to _project.json, this means that translation files will be created on the fly as the translator works, these translations are persistent and will not be deleted or disappear if _project.json is modified, they may however become inaccessible or untranslatable within Bilara due to the lack of collaborator or root information. If a project is modified, for example changing the translation_path to point someplace else, any existing translations would need to be manually relocated as required.

It is possible to manually add the translation files before Bilara has created them, for example if there are partial existing translation. Bilara will not be upset by a file already existing.

A project can be modified. For example, if the Klingon translation has gone very well, and Worf is ready to translate the rest of the Suttas, it would be entirely legal to change the paths to:

  "root_path": "root/pli/ms/sutta",
  "translation_path": "translation/tlh/worf/sutta",

This would not cause any problem with the DN translations, as they are still encompassed by the project.

add translation files or stubs define properties in _publication.json

It is also possible for translations to be added by virtue of their existence within the translation folder, even an appropriately named json file simply containing {} is enough, altough existing translations can also be added. However these files will have no "connection" with a root file and will not be able to be worked on without an entry in _project.json or _publication.json. If a file does not have an applicable entry in _project.json, then the bilara server will attempt to use _publication.json, specifically the root_lang_iso and root_lang_code properties to automatically find applicable root files.

Note that within the Bilara data scheme a translation can stand on its own and has no intrinsic connection with a root text (as a practical example, there might be multiple root editions in different languages which the translation draws from).

It is likely that at some point the Bilara translation app will no longer use _publication.json to determine root texts, and will require this relationship be explicitly defined in _project.json. At this point, _project.json will be exclusively used for the unpublished (working) branch, and _publication.json will be exclusively used for the published branch, with no overlap.

Clone this wiki locally