How to translate WikidPad into other languages?

Be careful when installing WikidPad again over your current version

For the translation you make changes to files in the WikidPad application directory. These changes may be lost if you install a new or the same WikidPad version over the current one. It is also recommend that you make backups of the original as well as the modified files.

Ensure that you have the right version installed

Basically you can use any version later or equal to 1.9beta13, but to thoroughly test your translation it is recommended to use the version for which you prepare the translation.

Use an editor which understands UTF-8 encoding

The translation files must be UTF-8 encoded. Under Windows 2000/XP, even the plain Notepad can handle UTF-8 without problems.

Poedit is a free cross-platform editor for .po-files, that make translations easier, especially when translations of new releases need to be updated. Untranslated and modified messages are marked in different colors sorted first in the list of messages that need to be overhauled, which means that you don't have to search for changes. When a new wikidPad release is available, open the .po-file and select "Update from POT file..." from the Catalog menu, to get the new and modified messages. http://www.poedit.net

Restrictions

Currently it is not possible to translate

  • special attribute names, e.g. "alias" or "bold"
  • shortcuts, e.g. always use "Ctrl-A", not (in German) "Strg-A"
  • external plugins

Special remark for a German translator

The included German translation file is a pure technical demo. You can use the translations in it or translate the words totally differently at your choice.

Step 1: Look if help is needed for your language

Look at wiki page XXX to find out for which languages translations are provided and how complete the translation is. If your language has a head translator on the list, ask him/her if help is needed (either by mail or through the wikidpad-dev mailing list.

If your language is not on the list you can add it and add yourself as head translator. It is recommended also to subscribe to the wikidpad-dev mailing list and drop a note there that you take over this language.

Step 2: Find your language code

Look at http://msdn2.microsoft.com/en-us/library/ms533052.aspx (but replace dashes here by underscores) or http://www.loc.gov/standards/iso639-2/php/code_list.php (2 letter language codes) in combination with http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm (country codes) and find the right code for your language. I recommend to be more specific and use the country code as well, but this may depend on your language. Use what you find appropriate.

E.g. for German, the code is "de", especially for German in Switzerland it would be "de_CH".

Step 3: Modify langlist.txt

In the WikidPad application directory there is a file "langlist.txt". Each line contains a language code and after a (real!) tabulator the name of the language written in the language itself (maybe you can't read some language names because your font does not support the characters, don't worry about that).

At the time of this writing, there is only an entry for English (which has the non-standard language code "C" for technical reasons) and a demo entry for German.

Append your language at the end of this list and save the file. This file defines the available entries in the options dialog.

Step 4: Get language template file

Retrieve the file "WikidPad.pot", rename it (this file may change with each new beta version of WikidPad, but does normally not change between release candidates of the same minor version) and put the file in the WikidPad application directory.

For file of version 2.2 see https://raw.githubusercontent.com/butscher/WikidPad/stable-2.2/WikidPad.pot

For file of latest alpha/beta version: https://raw.githubusercontent.com/butscher/WikidPad/master/WikidPad.pot

Step 5: Create/update your language file

If you are starting fresh with a new language, create a copy of "WikidPad.pot" which consists of "WikidPad_", then the language code, then suffix ".po" (no 't'), e.g. for German in Switzerland, it would be "WikidPad_de_CH.po". Put the copy in the application directory.

If you have already a language file and want to update it with a new version of "WikidPad.pot", first make a copy of your language file (just to be sure), then call WikidPad from command line with parameter "--updtrans", then the name (and maybe path) of the language file, then with name (and path) of "WikidPad.pot" (if this is in the WikidPad application directory, you can omit the last parameter).

Example (for Windows binary) if everything is in the right place and WikidPad is called from inside the WikidPad application directory:

WikidPad --updtrans WikidPad_de_CH.po

Step 6: Edit the language file

The .po file consists of three components:

  • Comment lines beginning with "#". It makes no sense to create or modify them as they are overwritten with the next update from a "WikidPad.pot" file.
  • Message ids. These begin with the keyword "msgid" and contain in double quotes the English text of the message.
  • Message strings. These begin with the keyword "msgstr" and contain the translated text of the message id above it. For not yet translated messages this is an empty pair of double quotes.

Message ids and message strings can span over multiple lines. The first one must begin with the appropriate keyword. Each must have an opening and a closing double quote of it's own.

Some characters have a special meaning inside some or all messages, combinations of these characters may occur:

Backslashes '\'

These are special inside all messages. A backslash plus one other character represents some special character. Of main interest are:

  • \n which represents a new line
  • \t represents a tabulator
  • \\ represents a single backslash
  • \" represents a double quote

The following example is the entry for the help message you get when running WikidPad from command line with the "--help" parameter. Each line is terminated by \n:

#: lib\pwiki\CmdLineAction.py:173
msgid ""
"Options:\n"
"\n"
"    -h, --help: Show this message box\n"
"    -w, --wiki  <wiki path>: set the wiki to open on startup\n"
"    -p, --page  <page name>: set the page to open on startup\n"
"    -x, --exit: exit immediately after performing command line actions\n"
"    --export-what <what>: choose if you want to export page, subtree or wiki\n"
"    --export-type <type>: tag of the export type\n"
"    --export-dest <destination path>: path of destination directory for export\n"
"    --export-compfn: Use compatible filenames on export\n"
"    --rebuild: rebuild the Wiki database\n"
msgstr ""

Ampersands '&'

These are special for some messages.

If a menu entry or text in a dialog has an ampersand, the letter or digit following it is shown as underlined and pressing ALT plus that letter activates the menu entry. This only works of course if the same letter in a menu or dialog is not underlined multiple times, e.g. "&Cut" and "&Copy" would both have the "C" underlined and pressing ALT-C would be ambiguous.

As you do normally not see all messages of one dialog at once together in the language file it's hard to decide which letter to choose for highlighting, but don't worry too much as normally errors here should show up soon after the version is released and can then easily be fixed.

By the way: I do not know a way to show a real ampersand inside such messages.

Percentage signs '%'

These are special for some messages.

Percentage signs followed by a letter (normally 's', 'i' or 'd') are placeholders for a text or a number which is inserted by the program before displaying the message.

Example:

#: lib\pwiki\AdditionalDialogs.py:177
msgid "'%s' is not an existing wikiword. Create?"
msgstr ""

In some cases a message contains more than one percent sign plus letter. In this case it is important that the translated message uses the signs in the same order as the English one. If this is not possible or wouldn't sound well, please contact me.

Example for multiple signs:

#: extensions\referrals.py:90
msgid ""
"*%s page(s) referring to* %s\n"
msgstr ""

To show a single '%' in the output message, use two percent signs '%%'.

Double question marks '??'

At the time of this writing they are not in use, but this may change.

Sometimes the same word in English must be translated differently related to its context. E.g. "file" may relate to the noun "a file" (in German "Datei") or the verb "to file" (in German "ablegen"). I painfully remember the old Netscape Composer 4.0 where this was done wrong in the German translation.

To distinguish that, the untranslated message can have '??' and comment after it (I call this "discriminator"). With the example above we would have e.g. "file??noun" and "file??verb" to translate.

Do not add the '??' and the comment to the translated message!

Step 7: Testing the language file

Now run WikidPad. If it gives an error message on startup, there may be a syntax error in your translation file. You can get a vague hint (unfortunately not more) where to search for it by opening the "WikidPad_Error.log" file, if present. The directory (= configuration directory) of this file can be found by using "Help"->"About" in the menu and scrolling the info text down to the end (you should do this of course before placing the translation file which can cause the error).

If WikidPad starts your file it is either OK or WikidPad does not use it yet.

In the second case open the options dialog, page "User interface", entry "UI language". The list there is fed by the "langlist.txt" file and should contain your language as well. Choose your language, then terminate and restart WikidPad. It may now give an error message as described above.

Step 8: Transferring translation back to the project

You need an account to WikidPad's Yahoo group to place your translation here.

It is important to include the WikidPad version in the filename. E.g. the name for language German in Switzerland for version 1.9beta13 would be "WikidPad_de_CH_1.9beta13.po".

When asking for help

Especially when you want to know the precise meaning or context of a message and you want to ask me, it is important that you include the line(s) beginning with '#:' directly above the "msgid" and to tell me the version of WikidPad you are currently translating. These lines contain often file names and line numbers in the code where the message appears, so I can look there and tell you about the message.