Preface - theWord



Preface

This document explains how you can translate ‘The Word’ (called TW in this doc) into your own language. TW can be translated even in Unicode-only languages. If you intend to translate TW into your own language you must read and understand this document. If you want the translation you make to be made publicly available to other users and officially accepted and published from TW main site, you will have to submit the translated files and resources to me with a note saying that all copyright of your work is released to me and I will have the right to further use, change and distribute the translated file.

Visit and the forums here:

What is translated?

The translation of the program refers to the messages, menus, buttons, etc that are found from within TW. The add-on modules (or resources) that accompany the program (e.g. Bibles, Commentaries, etc) are outside the scope of the translation of the program itself. Almost every single message of TW (>99% of messages) can be translated. There are only very few error messages (that normally do not appear to a user) and some command-line advanced options that are not translated (99,9% of the users will never see these).

Where are the messages stored?

All messages used in the program are stored in simple text files with the extension .lng. These files can be found in the same folder as the main executable file (theword.exe). If you are unsure, you can open TW, click on menu Help->About, click on the File locations tab and from there see the folder of the .lng files (Language files folder).

The default language file that comes with TW is in English and is called english.lng. Before proceeding, you can open this file in a text editor (e.g. notepad) to see what it looks like and get a first idea. For version 3, there are about 2000 messages to be translated. This amounts to about one week of full-time work.

Apart from the messages, there are 2 special things that need to be translated:

1. The Search Patterns: this is a section in the file that is connected with the Clipboard Monitor (you can read below)

2. The Notice section that contains the text that appears when you click on the Help->Donate button. For the translation of this text you will need to use MS Wordpad that comes preinstalled with windows. There is a special procedure to translate this, although it is very simple.

Format of the language file

The information in this section is a bit technical. If you cannot understand it, don’t worry, just ignore for now.

The language file is a Unicode file, encoded in UTF8 (don’t worry if you don’t know what this is, keep reading). All lines in the file that start with # are comments and are ignored by the TW. The language file is separated into sections. Each section has a name enclosed in square brackets []. The first section you can see is called [_main_]. Each section starts from the [] line and ends where the next section starts. Each section defines messages for a specific window/dialog/part of the program. Before each section there is usually a short comment that explains how to display the dialog that contains the messages of the section.

There are 5 special sections:

1. [_main_]: this is the first section at the top of the file. This section is very short and only contains a few entries. The [_main_] section including all it’s messages should NOT extend below the 20th line of the file.

2. [Messages]: this section contains general messages that appear usually at user-dialogs or are used to created longer messages.

3. [Books]: This section contains translation of the books of the Bible used throughout TW.

4. [Search.Patterns]: This is at the end of the file. This section is used for the Clipboard monitor function of the program and needs special care. See relative section below.

5. [Notice]: This section is used for the Donate dialog. It requires some special handling since the text is encoded in RTF.

How to start a new translation

Let’s suppose that you want to translate the program into Greek. First thing to do is to create a copy of the english.lng file and name it greek.lng. This copy should be in the same folder as the english.lng file. Open the file and change the first entries in the [_main_] section, specifically the name and langid keys. So, your new greek.lng file should look like that near the top:

[_main_]

name=Greek (GR)

langid=1032

…

The name key is used for the File->Languages menu. Once you restart the program you should see your new translation at this menu. The langid key is the language identifier. Please, consult the forums or mail me to obtain the correct one for your language. Now you are ready to translate your greek.lng file. Please, keep reading!

1 Format of entries in the language file

This is the most important section of this document. Please, read carefully before attempting any translation.

Each entry in the language file is of type key='' and exists in a single line. Notice the 3 parts of the entry:

1. key: this is an identifier that TW uses to locate the message. When translating TW you should not change the key in any way. If you change a key, then TW will not be able to use this message at all. The key is quite descriptive and may help you understand (when viewed side-by-side with the dialog that the message appears) where exactly the message appears.

2. =: (the equal sign =). This comes after the key and before the translated message. Don’t use spaces there please.

3. '': This is the translated message. This is what you need to translate. Notice that the message is enclosed in single quotes. Failing to format the message properly will result in errors.

1 '' format and notes

It is important to say a few things about the translated message.

1. Notice that it is always enclosed in single quotes (' … '). If you need to use the single quote character (') within the message itself, you need to type it twice. For example:

lblTip.Caption='Please, don''t close this dialog'

Notice that don't is written with 2 single quotes as don''t. This message will appear in the program with one single quote. This is the most common error you can do. If you make a mistake and use a single quote within a message, then this message will NOT appear in the program at all.

2. You will notice that the & character is used in menus and dialog items. When & comes before a letter, then this letter will appear underlined in the program. The user will be able to access the menu or function this item describes using the ALT key and the underlined letter. To understand this: search in the english.lng file for the actFile.Caption entry (use the Search function of your editor). Notice that it looks like this:

actFile.Caption='&File'

Notice now in TW at the main menu the File menu. Notice that F is underlined. This is because of the & before the F in the ‘&File’ item. Click on TW and press ALT+F. Notice that the file menu appears.

The character after the & is called ‘shortcut character’. It is important that you don’t have duplicate shortcuts in a dialog. If you do so, the program will not be able to know which function should execute when the ALT+ combination is pressed. Notice that this is a ‘per-dialog’ setting.

If you want to use the actual & character in a message, write it twice, for example:

lblTip.Caption='Tips && hints’

This will appear as Tips & hints in the program (notice that if you had only used a single &, it would appear in the program as Tips _hints).

3. You will notice that in some messages, the #13 or #9 appear. The #13 means “new line”. From TW3 onwards, long messages in hints wrap automatically (when updating old translations, you should remove those #13 that were put just to wrap lines). Please, be careful since some #13s are there because they start a new paragraph. For example, notice the hints in the Bible search view -> Detailed tab -> Operator buttons (the ones below the input box). Notice that they have very long hints (e.g. the NearV button, check for cmdOpNear.Hint in the lng file). Notice here that there are several #13 in order to format the message properly. The first sentence (although is quite long) has no #13 within it, it automatically wraps. The #9 is used for tab characters. There are very few, just keep them as they are within your translated messages. Notice also that the #13 and #9 are outside the single quotes. So, if you want to write a message with a new line, you should do it like this:

lblTip.Hint='This is one line'#13'This is a second line'

Notice that the single quotes close before the #13 and reopen after it. No spaces there!

4. Keep the %s and %d you find in the messages. Usually, in messages that are assembled from other elements, there are placeholders. These are special strings (e.g. the %s and %d) that represent a string or a number that will be replaced there before the message is being shown. It is important that the order of the placeholders (and of course the exact number) does not change (or a program error will occur). For example,.

rc_booksearch_found='Found %d matches in [%s]'

This message appears in the book search view (F2) just below the input box when a search is done (it says how many hits where found). Notice that the %d represents the number of matches and the %s represents that name of the module being searched. These are replaced before the message is displayed with the appropriate number and title. Now, if you want to translate this to another language, you need to keep the %d and %s in your translated message in that order. For example you can write it:

rc_booksearch_found='%d hits detected in (%s)'

(obviously this is not a translation because you wouldn’t understand Greek, just another way to write the same thing -think of it as your translated message). Notice that the %d and %s are still there in the exact same order.

If you find a message with %% in it, then you have to use them if you want to use the actual % character. Example:

rc_bookview_idx_progress='Creating index for %s: %d%%'

The last %% will be printed out as a single % (this message prints the percentage of the index being created, e.g. Creating index for MODULE: 23%). This rule only applies to a message that has at least one placeholder in it. If no placeholder is found in a message, then you just use a single % and it displays normally.

2 Tips for translating

1. While translating, try to keep empty lines and comments as they are. This will make it much simpler to compare your file with the original one.

2. Respect the spaces in existing messages. For example, if you see a space at the end of a message (or before it) you should keep it. The reason is that usually this message is a part of a bigger one and the space is needed when the big message will be assembled.

3. Use the CTRL+SHIFT+L combination on your keyboard to force TW to reload the current .lng file you use. This is the single most useful tip when you translate. The CTRL+SHIFT+L is a global windows combination: you can press it while you are in your favorite editor, and TW will reload the language file. This is the method you should use often to see your messages (and not restart TW).

4. Please, end all long hints (e.g. messages where the key is item.Hint='…') with a period (.). ‘long hints’ are considered the ones that contain an explanation of the function, apart from a short-description of it. There is no definite rule, check what’s best.

3 Checking your language file for errors

No matter how hard you try, your translated file may contain syntax errors (e.g. missing quotes or entries that are malformed in a way that are not recognizable). Once you finish the translation of the language file you must use the ‘LngChecker’ utility to check it’s consistency. Please, download this utility here:

(uncompress the file, contains a single .exe).

Execute the file and select the english.lng file as template, and the file you just translated to compare. Please, check and resolve all possible errors.

Tools to help you translate

The simplest tool you can use is notepad that comes with windows itself. There are though much better editors than this one and I would personally suggest to use one of the 2 suggested. I personally use ‘Ultra Edit’ () but it’s not free. There are several other free editors you can use such as notepad++ (), PSPad () and others. I suggest that you use notepad++.

Now, although my favorite tool to do the job is an editor, there is also another very good tool that helps the translation a lot, called IniTranslator.

IniTranslator program

You can download this software from here:

This is a very useful program that will make the whole translation process much easier. Please, keep in mind that:

1. This is a separate program which I have personally not used (others have with good results)

2. If you use it, the [Search.Patterns] and the [Notice] sections will be deleted! You need to add these later manually. Be very careful here. Some manual editing will be necessary for these sections.

3. Comments are not pasted in the translated file (you can always open the original english.lng file of course to check)

Here are some hints to better use this program:

1. In File->Preferences->Advanced click in Encoding for new files and select UTF-8.

2. Make sure that all your translated messages contain single quotes and follow the rules of single quotes mentioned above.

3. Check all the File->Preferences options before you start, to make your life easier.

4. Press CTRL+M to open the ‘comments’ dialog: you will be able to see the comments in the original file.

5. Experiment with the alternate way to translate by going to menu Plugins->Tree View. This view properly shows the single quotes there and it may seem easier.

IniTranslator can use dictionaries for common words. It is very interesting to download and use the “Microsoft Terminology Translations”. This is a list of common words that are translated from Microsoft in several languages for Windows. This will help you to properly translate some difficult terms (e.g. Hierarchy, View, Edit) using the words that Microsoft also uses for it’s products (MS Office, Windows, etc). To use such dictionaries you need to:

1. Go to and download the file including all dictionaries. Unzip the file in a folder.

2. Use the MS Terminology Translations converter which is installed with the InitTranslator (go to the start menu, under the IniTranslator section, you will find a shortcut there).

3. With this tool, create a dictionary for the language you want to translate.

4. Now, from within IniTranslator, go to Dictionary -> Load dictionary menu and load the dictionary you made. Now, when translating, you can find for some messages a translation (right click -> Dictionary).

5. Check the help file of IniTranslator, under the MS Terminology Translations builder section.

Special sections

1 Section [_main_]

This is the first section of the .lng file. It should not extend below the 20th line of the file. The name and langid keys are described above. The version key is not used in the program but you should use it in order to properly identify the version of the language file. Please, use the format -. Each time you update this file, you should increase the by one. The should always be the version of TW you used to create this lng file. Please, be consistent with this.

The font key is optional. If it is defined, then this font will be used for all menus in the program. This is only applied at program startup (not when changing language). If unsure, don’t include this key (leave it commented out with the # in the beginning).

2 Section [Books]

This section contains the names of the books of the Bible. The books of the Bible are numbered from 1 (for Genesis) to 66 (for Revelation). To easily find the number for each book you can use TW: open the program, press F8 so that the Bible tree is visible, then on the small toolbar of the Bible tree view, click on the 3rd icon and select Book numbering -> Active. Doing so, the number of each book will appear in the tree. You can use now this tree to find quickly the number for each book of the Bible.

In this section there are 2 lists: one for the full book names and one for the abbreviated book names.

The full book names list has entries: rc_bk_alias1_1 … rc_bk_alias1_66.

The abbreviated book names list has entries: rc_bk_alias1_3 … rc_bk_alias3_66.

You need to provide the book names for both lists.

The rc_bk_def_alias property at the beginning says which list should be the default (leave as is).

3 Sections [Search.Patterns]

This is a special section. It is always towards the end of the .lng file. The format of the entries in this section is different than the others. Notice that if you use the IniTranslator utility to make the translation, this section will be automatically deleted. So BE CAREFUL not to delete this accidentally in your translated .lng file.

This section is used by the Clipboard monitor (CM) utility. Please, see the help file if you are not sure what this is (quick help: it automatically locates verse references in texts and displays a popup window with the verse text). This section defines the patterns being used from the CM function in order to identify Bible book names.

The format of the entries in this section is |.

The corresponds to the index of the book of the Bible (1 .. 66).

The is used to identify a Bible book name, and is the one that is used (matched on a search) in two places:

1. In the 'Verse reference (F4)' box on the topmost toolbar (where you enter a verse reference).

2. In the "Clipboard monitor" feature to scan book names within arbitrary texts 

The rules that are used for the are as follows:

• The search is happening in order. From pattern 1 until the last one.

• For a string to match a pattern the rule is: "all letters in the string should be found in the pattern, in the same order they appear. If some letters in the pattern do not match then this is OK as long as the order of the letters in the string are preserved".

• The first letter of the pattern should match the first letter of the parsed word.

• There can be multiple patterns with the same .

• If more than one pattern matches, then a score is assigned to each match. The match with the higher score is used. The more close the letters of the searched word are matched with the pattern the higher the score (see examples below).

 

Examples:

 -The 'Mark' book will be matched by: M, Mk, Mark, Mrk, Mr in English. All these strings follow the above rules.

- For 1Cor book, one pattern used is

1.Corinthians1|46

Notice that there is a dot after 1. This means that both 1Cor and 1.Cor will match

- Scoring example: notice that in the enlish.lng file there is the entry P0hilemon|57. Notice there is a 0 after the P (this is not a mistake). This 0 will not break this pattern, on the contrary it helps to always score this entry less than Philippians|50. Suppose, a word is found in a text to be parsed as "Phl 1:1". Now, both P0hilemon and Philippians match Phl. But notice, that Philippians contains all 3 letters of Phl (P, h, l) closer to the first letter of the pattern (P). This will give to Philippians a higher score and will be selected as the best match for Phl.

- For Greek there is the following entry for Mark:

    ΜΑΡΚΟΥΝΣ|41

Actually, the Greek book name is: ΜΑΡΚΟΣ. Some older bibles use the word ΜΑΡΚΟΝ (notice the N instead of Σ at the end). The same book can also be found (when referred in second person) as ΜΑΡΚΟΥ and other times as ΜΑΡΚΟ (without the final Σ or N).

Now, the entry in the greek.lng file says ΜΑΡΚΟΥΝΣ which is completely wrong as a stand-alone word. BUT it matched all the above 4 different cases that one could write for the book of Mark. From this example it should be obvious that following the above rules, the entries here do not need to be 'correct', they just serve as matching patterns. That is why there are generally more letters than normal.

 SO, the logical rule for this section is:

"Since words mostly change at their ending, add the book names with ALL the possible different endings appended in such a way that one does not contradict with another."

If for a book, two completely different forms are possible, just add two or more entries with the same . So, for "Habakuk" you can also add an entry with "Habakkuk" in case someone uses two k.

For Obadja you could write Obadjia if some people could write it as Obadia and others as Obadja.

Generally, using more letters will not break a pattern. For example 1.Thessallonnians|52 is a good pattern since people may not remember if it is written with ss or ll or nn. This pattern will match all the cases.

For books with more than one index (e.g. 1Samuel and 2Samuel) you can add: 1Samuel, ISamuel, Samuel1 and any other combination as different entries (remember, you can have multiple entries for a single book.

1 Search patterns exception

Due to the nature of the CM, it is possible that many common words will be incorrectly located as valid book name. For example, the common English phrase "Am I“ will be parsed as Amos 1 (Am will match Amos, and I is the roman number 1).

To avoid such common word errors, it is possible to add patterns in this section that start with a minus/hypen character, e.g.

-ami|0

In these cases, the pattern (which is ami here, as the minus is ignored), will work as an exception, e.g. they will disallow a match. It is really difficult to predict or try to think of exceptions. The best way to add some common exceptions for your language is to use the CM in some web texts of your language (e.g. browse the Internet, find pages with a lot of text and select/copy them so that CM gets a chance to identify verse references. Noticing the probably false negatives, you may be able to create a short list of exceptions. If this seems complicated, just ignore it and add no exceptions.

4 Section [Notice]

This section contains the text that can be found in the Help->Donate dialog. It is special because it includes formatting. In order to edit this text properly you will need to use MS Wordpad (you could also use MS Word and save as rtf, but Word produces large rtf files and includes a lot of unnecessary info in the rtf file). Follow these steps:

• Get the original rtf file from (this contains the english version).

• Open the file with Wordpad, translate it and save the file. Please, retain all formatting as is. Don’t translate the name of the program The Word that appears at the top of the file. Please, retain also all colors of the text (especially for the links at the bottom, they should be blue and underlined).

• You should NOT translate the last sentence of this file (This notice was originally written in English. Since a translation may not accurately express the thoughts of the writer, you may read the original version at: ) ). This last sentence should remain as is.

• The saved file has an extension .rtf. Open this file with an editor (e.g. notepad) or the editor you use and copy all it’s content. Paste it under the [Notice] section in the .lng file. That’s it.

A critical notice: the program will NOT display the translated notice if:

• The rtf content is corrupted (e.g. if you forgot to copy/paste the last } character).

• If the content is not quite ‘similar’ to the English text (similarity is counted in a way that assures that the content and formatting is retained during the translation).

-----------------------

9

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download