How To

Atom - the text editor

With Atom you can open up whole directories and have it display the files in a tree-structure. You can also add two different folders to the project. We recommend adding both the english and the [your language] folder into the file-view. And then you split the edit-window and keep the original file in one window and the translation in the other window. That way its simpler doing the translation. You can also view a webpage such as inside Atom alongside the files you are editing if you should want to. It means you can have everything on one screen like this:

Atom Screenshot 2+1. Two open files and Web Browser

A tip: When you are using the Atom editor you can start it from command line and have it open a directory like this “atom [dir]” (if Atom is added to your path). Or simply open Atom and SHIFT+CTRL+O - and select the folder. It will show all the files to you from the given directory and its also easy to search for text within all the files using: SHIFT+CTRL+F - as well as replace text directory-wide and not just in the given file. Download the Atom Editor from

Calibre for e-pub files

In order to view an e-pub file you need an e-pub reader. E-pub readers are available for all types of smartphones and tablets and computers. For a free e-pub reader on Windows, OS X or Linux we recommend Calibre. Please note: Calibre does not delete your old e-pub files. It means that whenever you receive a given e-pub the second time you need to first delete the old one in Calibre before importing the newer one! If you fail to do this you will be thinking you just imported the new one and at the same time asking yourself where your latest changes are :-) Many have been puzzled by this until we tell them!


If you should have a problem unzipping or uncompressing the file(s) we give you, try using 7-Zip.

Encoding of files

All the files we share with you will be UTF-8 encoded. If you dont know what that means, but use Atom to edit the files then it will remains UTF-8 since it preserves the encoding. Other editors may change it when you save, which causes unnecessary work :-(

Bible names

The bible-names file is located in the _resources directory and is the names:[your language].csv file. This file contains all the 66 Bible names from Old Testament and New Testament of The Bible and they need to be translated and or proofread, preferrably using the Atom editor. Please make sure these are 100% correct.


The keywords used throughout the e-pubs are located in the translator:[your-language].csv file and should be edited using a simple text editor (like Atom), not excel or any other fancy editor - which then often saves it in a proprietary format or changes the encoding :( So, the first column is the id, second column is English and the third is the one to be translated and or proofread.

Below is an example of some of the Polish keywords:

English Polish
chapter rozdział
next chapter następny rozdział
previous chapter poprzedni rozdział
The Old Testament Stary Testament
The New Testament Nowy Testament
verse index główna verse
chapter index główna sekcja

For an example of the complete English-Polish keyword list go here.

Actual Editing

Please be attentive when you edit the texts, in order to avoid introducing errors on the tags or parameters. Each error introduced potentially means several minutes trying to fix it again. We really want to avoid that if possible.


Once the translation is done you will need to proofread it. We will build two e-pub files based on the new translation. One for the standalone language and another with the new language in parallel with english. Both needs proofreading on the titles and contents of the foreword and keywords. We would also appreciate if you notify us of any errors on the covers if you see any.

Send us the changed file(s) in a file named [your language].zip. If you proofread or edit a single file send if one by one. If there are errors and you have perchance messed up a parameter or an xhtml-tag, the e-pub build will ‘crash’ and we will need to find the cause and correct it before we can continue, so we dont want all of the files each time if you only correct one file.

Dropbox Client

We can use Dropbox if you want to. For those who dont know about it. Go register an account at and download their client. Install it on your computer and then give us your dropbox-email at We will then share the folder with you with all the english texts.

Exchanging Files Upwork

If you are not using dropbox, all files will go through upwork. You will receive the from us with all the source-files or it will be attached the job description. Be aware that if any files are missing, you may receive them afterwards directly through upwork or otherwise, such as the epubs or other files needed to get the job done. Once you’ve completed the translation send the files back to us in a [your language].zip file. And if you are proofreading and only do small corrections, send one and one file through upwork, not the full zip-file. This needs repeating: Dont send the whole [your language].zip file when you only edit in a few changes!

Files & structure

The texts to be translated and or proofread is found in the file. It contains these folders:

  1. bible
  2. _resources
  3. text

In general, please do not make any name-changes to these files or change the parameters or tags. They are all text-files. Yes, the names end with xml, xhtml, csv and json, but the contents are simple text and they are easy to edit using any given text editor. The good thing about the Atom-editor is that it does not change the encoding, as other text editors just might do.

The bible folder contains one or more files in xhtml that each describe the given Bible translations we are using. If its not in the correct language please try and find a free text online describing the given Bible-translation in the the language you are translating to. Often we copy this from Wikipedia and make a small comment telling the reader where we copied it from.

The files in the _resources folder needs to be translated and or proofread. There is the titles-file, the translator-file and the Bible-names file. In the titles file only correct the line that says “title” - and notify us if the subtitles are incorrect and if the Bible-translation in your own language is wrong. Also, please do not use Roman Numerals like III, II or I in the numbering of the Bible-books, but use Latin numbers like 3,2 & 1 or the words First, Second or Third before the Bible names depending on whats normal to use for the Bible in your language. The translator-file contains the key-words we use throughout The Digital Bible. Most are used, but some are not at the present time. We are not linguists so the titles and the keywords are either taken from Google Translate or our creative (read: pretty wild at times) minds :-D - so they need to be corrected and proofread.

The files in the text folder are somewhat technical in nature as they contain parameters and xhtml tags all mixed. Please see the description on the tags and parameters on this page. When we build the different digital books the files within the text-folder is what makes up most of the introduction to The Bible. And the last chapter, ‘Our Publications’, is also included in this. It can be somewhat difficult to navigate them and find the correct file when you are proofreading, but Atom has a great file-search function. Use its File->Open + Folder and choose the root folder to the unzipped files. Atom will then show you the folder structure on the left side - and you can use its file search function with Shift+Ctrl+F or through the menu File->Find in Project and search for bits and pieces of the text from the epub you are reading. The only thing you need remember is that some of the texts in the epub are generated using software where we knit together Bible names and keywords - so you cant expect to find everything in the files by doing a simple search, so a few tries may be needed before you are able to locate the original file from which the given line in the epub was made. Hopefully we didn’t mess up trying to explain this, but in case this was a bit difficult to understand just ask us and we will help to the best of our ability.


Its very important you do not change any of the xhtml tags or part of the parameter(s). Removing one simple } or > or adding spaces within tags will crash our epub-build-engine. A translator typically introduce a handful of mistakes into the text this way, but please try to be observant when you edit the texts in order to produce as few technical mistakes as possible! A few translators have given us an error-free text so its possible to do this. So, we encourage you to know exactly what you are doing before moving a parameter or trying to work ‘around it’. If you do this, all will be well :-D And if you mess it all up, hey - you’re human like us ! But it may take us an hour or so to fix up the mess afterwards if the problem is ‘hard to find’. Also - before you do any new edits after we have generated the e-pubs, be sure you do so with the files we send back if we have helped you in correcting any technical mistakes you make :)

Parameters versus text

Ok, so this is the not-so-easy part for some. Always pay close attention and be sure everything is crystal clear :-D Throughout the text you will find parameters and text, mixed or separate. A parameter always begins with ${ and ends with }. It always has a specific name and and could be either a conditional parameter or simply a parameter like ${href_tot_num}. If its a conditional parameter it will look like this: ${[study_bible==1]Study Bible}. You see the ==1 within the parameter? Thats the condition. It basically means if the parameter study_bible is set (positive or above zero), then the rest of the text between ] and the ending } will be included in the final result. In this instance it means Study Bible will be included if the study_bible parameter is set to 1 or True and the parameter name and tags will disappear and only Study Bible will be visible in the end-text.

You will find that some parameters have cryptic names and others dont. Thats why we advise you to actually open up the example e-pubs we have provided and see the result of current translations. Below is a mixed example of the most ‘difficult’ parameters, mostly taken from the main.xml file:

<hx id="foreword">Foreword</hx>

<p>This ${[drm==0]DRM-Free }${[study_bible==1]Study Bible}
${[study_bible==0]publication} contains ${secbibtype_short_txt}
${[secbibtype==1]parallel} translation.
${statistics.xml} ${[navi_bible_build==1]navi_build.xml}
${[link_bibles_build==1]Most of the verses in the Bible
formats are interlinked, so
switching from one format to the other is
usually only a click away.}</p>


${[dict_count==1]It holds ${dict_count} dictionaries.}
It has ${href_tot_num} references
and shows ${format_count} formats of The Bible.

The [some-name].xml parameters are references to files. It means the parameter itself will be replaced with the contents of that file in that specific location. Lets take ${[tts_bible_build==1]tts_build.xml} for example. First you have the tts_bible_build==1 check. If its true, the whole ${[tts_bible_build==1]tts_build.xml} will be replaced with the contents of the tts_build.xml file.

The your-language]-titles:proposal.json needs to be translated and or proofread. Only correct the title line in the your-language]-titles:proposal.json file, not the other lines:

        "sku": "ylt-nor1930-pv",
        "title": "English Norwegian Bible",
        "subtitle": "Young's Literal 1898 - Bibelen 1930",
        "comment": "English Norwegian Bible",
        "date": "2017-04-02 12:37:31 (Norway)",
        "nr": 1
        "sku": "gen-hbr-pv",
        "title": "English Hebrew Bible",
        "subtitle": "Geneva 1560 - Hebrew Modern",
        "comment": "English Hebrew Bible",
        "date": "2017-04-02 12:37:31 (Norway)",
        "nr": 2
        "sku": "bbe-nyn-pv",
        "title": "English Norwegian Bible №2",
        "subtitle": "Basic English 1949 - Studentmållagsbibelen 1921",
        "comment": "English Nynorsk Bible",
        "date": "2017-04-02 12:37:31 (Norway)",
        "nr": 3

So, the lines with “title” and “subtitle” needs proofreading and all [your language] lines in translator:[your-language].csv needs to be proofread/translated. Dont change the english column in translator:[your-language].csv.

Roman Numbers

In the titles-file in the resources-folder (and possibly other files in the project) you will find Roman Numbers. Please do not change these to latin numbers. This is the way its supposed to be and so no ‘translation’ is needed on these. This goes for all files with Roman Numerals in them. Do not convert these to Latin numbers. Like I, II, III, IV, V, VI, VII, VIII, IX, X and so forth are to remain the same and unchanged. We didnt expect this, but some translators did so thats the reason we’re exlicitly pointing this out.


When you have finished your work please go to the feedback page!

If you have any questions, do not hesitate to ask us at upwork 😃