Translating NVDA into other languages (NVDA localization)

By Cleverson Casarin Uliana, last modified Jan 15 2010

Note: to fill in edit fields, save files, and create folders as explained later, you must keep the letters cases as they appear in this tutorial.

You are expected to have the NVDA's source code version installed and working fine on your machine. For these instructions, I assume you have Python 2.6 installed in c:\python26, and NVDA's source files installed in c:\NVDA\source.

Localizing NVDA

Possible Translation Methods

There are at least two methods you may use to translate NVDA. One is to use some commands to generate the file containing the strings to be translated, then use any text editor to translate them, and finally use another command to compile the finished translation. Another method involves using PoEdit, a program with a nice GUI to hold all of the original and translated strings. I'm going to explain this method first.

Installing and running PoEdit

PoEdit's homepage is:  http://www.poedit.net/

You can always download the latest Windows PoEdit version at:  http://sourceforge.net/projects/poedit/files/

Install it by following the on-screen instructions. Except for the second screen, where you must check the "I agree" option, I suggest to accept all of the default options, especially in the components screen, where you must perform a full installation.

When you run PoEdit for the first time, the first screen is for you to choose the default language for the program's menus, windows and options. It probably will default to your system language. In this tutorial, I'm going to refer to PoEdit menus and options by their English names.

The next step is to enter your name and e-mail for PoEdit to fill in the headers of the strings catalog files properly. Enter them at the respective field in the window dialog that appears. Next, press control+tab until you reach the "parsers" tab, then find the list of languages and select Python. Tab to the edit button and hit space bar, then tab to the "list of extensions" field and append a semicolon followed by "*.pyw" to it. The field must look like this:

*.py;*.pyw

Next, find and press OK to close the Python parser window, then press OK to close the prefferences window, since all other options may be left as default.

creating the NVDA Translation Catalog

Go to the file menu and click on "New catalog...". Here you must enter some more info for this specific project. Almost all of the fields are optional, but entering correct information is always desirable.

In "Project name and version" you may put "NVDA R" followed by the last revision number you checked out. It might be for example:

NVDA R3461

In "team" you might put something like "<your language code> language team" or simply your name if you are the only translator. In "team's e-mail address" put your e-mail. Next, select in the combo boxes the language and country for your project. In the charset and source code charset combo boxes, select "utf-8", as NVDA is written in Unicode.

Next, press control+tab to go to the path tab, then enter in the base path edit field the absolute path of the folder where you downloaded the NVDA's sources to, e.g. "c:\NVDA". Tab to and press the button that follows, then enter "source" in the edit field and press enter. This is the path from where PoEdit will scan the source code for translatable strings. Tab to OK and press it.

A "Save as" standard dialog will appear. Type "nvda.po" in the file name field, then choose the folder "NVDA\source\locale\<languageCode>\LC_MESSAGES", where <languageCode> is actually the code of the language to which you are translating NVDA, in the ISO-639 format. If such folder structure does not exist, create it.

PoEdit will then save two files in that folder. "nvda.po" holds all the original and translated strings in text format. You may check it using any text editor whenever you want or need it. "nvda.mo" is the binary version of nvda.po; it's the file NVDA actually reads and assumes at its runtime.

Just as an info, If you preffer using the pygettext command line tool instead of PoEdit, as explained later in this tutorial, there will be another file called nvda.pot, which holds all original strings; you have to save it as nvda.po after translating. PoEdit needs not to generate a pot file, as it can scan the source code and update the PO catalog automatically.

You will now be presented with an empty list and a blank edit field, between which you can switch using tab. Go to the catalog menu and enter "update from source". This option instructs PoEdit to scan the entire NVDA source code for translatable strings. You must run it everytime you want to check whether there are new untranslatable strings to be added or obsolete strings to be removed from your project, no matter if it is or is not the first time you translate it.

After scanning the code, it may happen to appear a window giving some errors related to incorrectly terminated strings. You may simply ignore it and press OK, as they are just warnings without relevance. Next, PoEdit will present the list of new strings that are to be added to your catalog file, and the obsolete strings, that is, strings that are not part of the program anymore, most likely because some option had its name changed or had been replaced with one or more similar options. If it's the first time you scan the sources for strings, the new strings list will probably contain hundreds of strings. You need not to walk through all the list; simply hit OK.

Translating in PoEdit

You have now landed on the same list as before, but now fulfilled with all of NVDA strings to be translated. Read the status bar to see how many strings are translated already, how many are not, and how many are fuzzy. A fuzzy string is one that PoEdit has tried to automatically guess the translation, thus it may be wrong. To insert or correct the translation for a string, first select it with the arrows, then tab to the blank edit field and type its translation.

You may want to spell the original string to be aware of any punctuation mark, capital letters, etc. PoEdit has a keystroke you may press while on an original string, alt+C, that copies the original string to the edit field when pressed. You may then replace it with your translation normally.

Press control+s at any moment to save your work. Each time you press this key, PoEdit saves NVDA.po and also re-compiles NVDA.mo with the latest strings you translated and just saved.

Second Method: using Pygettext directly

If you are confortable using PoEdit, you may skip the rest of this page.

Open a command prompt and change to NVDA's source directory by typing: cd \NVDA\source

Now enter the following command: \python26\tools\i18n\pygettext.py -d nvda *.py *\*.py *\*\*.py *\*\*\*.py

This will generate a file called "nvda.pot" in your current directory, \NVDA\source. This generated file is a plain text which contains all of the specified strings to be translated.

Each line beginning with "msgid" contains an original English message surrounded by quotes. Each line beginning with "msgstr" contains empty quotes which should be filled in with the translation that corresponds to the original English message at the above line or lines. You should also fill in the first lines of the file, which hold the program's title, author, translator, language, etc. You should put an iso 639 alpha2 code of your language , e.g. de, en, fr, it. If the language is used in various countries and you would like to specify that you shal append an underscore and country code E.G. pt_BR, pt_PT, es_ES etc. You can look up your language code  here if you are not sure. In addition, don't forget to specify UTF-8 in the charset field and 8bit in the Content-Transfer-Encoding field.

Once you have prepared the file, save it with the name "nvda.po" in the NVDA's source directory.

Enter a command prompt, change to source directory and type this: \python26\tools\i18n\msgfmt.py nvda

This will generate a file called "nvda.mo" in your current directory, \NVDA\source.

Change to the locale directory under \NVDA\source and create a directory. Its name must correspond with the language code discussed above.

Inside this new xx_XX directory, create another one called "LC_MESSAGES" and place nvda.mo into it.

To run NVDA in your language go to the user interface settings and change the language. You will be asked to restart NVDA. Alternatively you can edit nvda.ini within the source directory, search for the line beginning with "language", and change the language letters from "enu" to the language code of your translation.

Now you are ready to run nvda.pyw and it should present the translated messages already.

Updating an Existing Translation

To merge an old translation with a new one, first generate an updated nvda.pot file.

Then download msgmerge.py from:  http://www.jantrid.net/misc_files/msgmerge.py and Place it in any directory. Here I have put it into \python26\tools\i18n.

Then go to a command prompt, change to the source directory and type: \python26\tools\i18n\msgmerge.py -U nvda.po nvda.pot You may like to create a batch file including these commands to speed it up.

This will update the translated nvda.po with the new messages from nvda.pot which are not translated yet of course.

Edit nvda.po and check it for misupdated lines, especially the first lines at the header, where MSGMerge doesn't do a perfect work. Then look for untranslated messages and translate them. Also make sure the strings which are translated properly don't have #, fuzzy comment in fromt of them.