The Word 3 translations notes, ver 0.5, 18-Jan-2010

1.  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: http://forum.theword.gr/viewforum.php?f=12

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

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

4.  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 [<section name>]. The first section you can see is called [_main_]. Each section starts from the [<section name>] 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.

5.  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!

5.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='<translated message>' 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.  '<translated message>': 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.

5.1.1.  '<translated message>' 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+<shortcut> 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.

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

5.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: http://www.theword.gr/files/utils/twLngCheck.rar (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.

6.  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’ (http://www.ultraedit.com/) but it’s not free. There are several other free editors you can use such as notepad++ (http://notepad-plus.sourceforge.net/uk/site.htm), PSPad (http://www.pspad.com) 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.

7.  IniTranslator program

You can download this software from here: http://initranslator.sourceforge.net/wiki/index.php/Main_Page

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