PsychoPy® is used worldwide. Starting with v1.81, many parts of PsychoPy® itself (the app) can be translated into any language that has a unicode character set
A translation changes the language that the experiment designer sees in the PsychoPy® app while creating and running experiments
As a translator, you will likely introduce many new people to PsychoPy®, and your translations will greatly influence their experience
Translations here do not refer to what the participant in a study sees, nor what is seen in documentation (help files, etc.)
In order to translate the PsychoPy® app to another language, you need a thorough understanding of at least three things:
PsychoPy itself, as an experiment designer yourself
the English language
the language you want to translate into (e.g., Korean)
You will also need an understanding of two more things. But in contrast to the above, these can be learned in less than a day.
For a more step-by-step tutorial for translators, please see the materials from our 3-hour translator workshop. You can go to the workshop slides, or the workshop webpage. The information is identical in both.
Importantly, everything in the rest of this tutorial assumes you have already done the following:
forked the PsychoPy repository on GitHub to your own GitHub account
cloned the repository to your own computer
Again, see the instructions on how to contribute to PsychoPy if you are unclear on how to do any or all of this.
If you are also working on things other than translations, consider creating a new branch based on the release branch, but rename it according to what you are going to do (e.g.,
translate-spanish). This will help you keep things organised in your own workspace. But if you are only doing translations, then just stay on the release branch.
When PsychoPy® starts, it consults a
.mo file, which was generated automatically from the respective
.po file during the latest release of PsychoPy®.
There is one default
.mo file (US English), along with any languages for which
.po files exist.
Translators modify the
.po file, not the
.mo file, which is binary and unreadable.
.po file you need for your translation¶
What you, as a translator, need to understand here is that in order to add any particular translation to PsychoPy®, you need to work on a particular
messages.po file for any given language is stored within a unique subdirectory within the following directory in the repository:
For any given language, the first pair of letters,
ll_, is replaced by an ISO 639 pair of lowercase letters that identify that language
For any given country, the second pair of letters,
_CC, is replaced by an ISO 3166 pair of uppercase letters that identify a country.
For example, for German,
de_DE, and refers to the German language (
de, for deutsch) as it is used in the country of Germany (
DE, Deutschland). Together, they index the dialect known as High German or Standard German (the upland dialect used as the official language in Germany).
Once you understand the naming conventions for language folders, your first order of business is one of the following:
finding the directory that corresponds to your language (in cases where it is already there), or
creating a new one (in cases where it is not).
If your language is not listed and you need to add it (or even if you are unsure whether you should be using the one already listed), scroll down to the section on Creating a new language subdirectory to learn more about what to do. Then return here when you are done.
If the appropriate language subdirectory is already listed, then proceed to the next section.
Open the relevant
ll_CC directory. You will see a subdirectory titled
LC_MESSAGE. Inside that subdirectory are two files. The one you work on as a translator is the
messages.po. The other file is
messages.mo, an un-editable binary file that actually turns out to be the file that PsychoPy® will use during operation.
.mo file is compiled during major and minor releases of PsychoPy®. It is also listed in the
.gitignore file. So you should not waste your time compiling it yourself within Poedit.
There are a number of tools you can use to edit the
messages.po file, but the rest of this tutorial assumes that you are using the free app Poedit. It is cross-platform, and very user-friendly. If you haven’t done so already, download Poedit and install it in order to continue.
How to translate the start-up tips in PsychoPy® is covered below under the section titled Step 3b: Translating Start-up Tips. It involves a related, but somewhat different process. First however, please read through the section directly below.
If you are starting Poedit for the first time:
File > Preferences (on a PC), or
Poedit > Settings on a Mac.
Go to the
For convenience, make sure that the box with the following label is UN-checked:
Automatically compile MO file when saving
As noted above, this is not strictly necessary as we have placed all
messages.mo files in the
.gitignore file, but compiling this file upon saving the
.po file would place an unnecessary burden on your computer.
Don’t add your name and e-mail address. Doing so would just unnecessarily make your name and email public on GitHub.
Go to the
Double-check to make sure that the following are set correctly
Preserve formatting of existing files
make sure this box remains checked
If you are the first person to begin translations on a particular
.po file (i.e., you have just created a new language subdirectory)
.po file for the language in the subdirectory you just created.
Translation > Properties
Under the tab labeled
Project name and version: Type in PsychoPy followed by the PsychoPy® version you are working on (preferably the most recently released version of PsychoPy®)
(Note that this is not strictly necessary; having the wrong version here will not affect anything else)
Language: Scroll to and select the appropriate language or language variety (language + country; see above)
Charset: Set this to UTF-8.
Under the tab labeled
Base path: Set this to the path on your computer that leads to the
psychopy directory within the cloned repository on your computer. Assuming you forked and cloned the psychopy repository in the usual way, this path would appear as follows on your computer:
Under the tab labeled
Additional keywords: Make sure that the keyword
_translate is listed in that box. If not, type it in.
Save your work (
File > Save)
Start your preferred text editor (e.g., TextEdit, Visual Studio Code, PyCharm)
psychopy/app/localization/mappings.txt in the repository
Find or type in the appropriate
ll_CC code at the appropriate line (entries are listed alphabetically)
Add the 3-letter Microsoft code that refers to the language. These can be found in the rightmost column (Language code) on Microsoft's list of Language Idenfiers and and Locales.
At the far right, make sure that there is a label for the language (and possibly country) that should be familiar to people who read that language, followed by the same in English, but in parentheses. The purpose is to highlight the name of the language (and possibly country) as written in the non-English language itself. For example:
español, España (Spanish, Spain)” (not just “
עִברִית (Hebrew)” (not just “
Save the altered
mappings.txt file in your editor
In some language varieties, like the example of Spanish above, you might find it appropriate to include the country of the locale as well. This is conceivably important for Spanish since there are varieties that differ significantly (e.g., Argentinean Spanish, Mexican Spanish). But notice that writing Hebrew, Israel would probably not be necessary since there is only one variety of the language that anyone would ever expect to see in a software program.
In Poedit, go to the
Translation menu and select
Update from Source Code. As long as you added
_translate to the keywords (see above), you should subsequently see a list of strings that need translating in your language. An example is shown below (from Swedish, which does not yet have any translations).
From the list, select a string that you want to translate.
Once selected, you should see it appear as English in the
Source text box below the list.
Type in your translation to the box under
Translation. A screenshot of the relatively complete file for Japanese is shown below.
If you think your translation might have room for improvement, toggle the
Needs Work button to the right of the
You can also add notes (to yourself and others, if any) by clicking the
Add Comment button to the lower-right of the app window if you have the sidebar visible.
Save your work (
File > Save).
Technical terms should not be translated:
Routine, and so on. (See the Japanese translation for guidance.)
If there are formatting arguments in the original string (
%(first)i), the same number of arguments must also appear in the translation (though their position in the translation would be dictated by the word-order rules of the language being translated into).
If they are named (e.g.,
%(first)i), that part should not be translated – here
first is a python name.
Sometimes, you will not understand what a particular function does in PsychoPy®, and you may be unable to translate it. There are a few possible things you can do in this situation.
Go to the PsychoPy Forum on discourse.org. There are friendly, useful experts there.
+ New Topic
Choose Development as the
translation as an
Type in your question in English, of course
The reasons for the category and the tag is to alert the people more involved with the underlying code of PsychoPy®
Determine it yourself
Place your mouse over the relevant string in the
Source text box and right-click it (control-click on a Mac). You can see where the string is defined under
Code Occurrences with the file(s), followed by a colon,
:, then the respective line number. You can then go into that file (or those files) to determine the function. Naturally, you need to understand Python quite well to take this approach.
If still in doubt, just leave out the translation until you do understand. There is nothing wrong with this approach. It is, by far, preferable to mis-translating a string. Use the
Needs Work or
Add Comment in Poedit, if you feel it is appropriate.
Instead of being translated as a set of strings in a
.po file, all of the start-up tips in US-English are stored in a separate, single
.txt file called
tips.txt. This file is then generated as a string under
Source text - English in the
.po file. If there are translations of these tips for another language, they are stored in a separate
.txt file in the same directory, but with a different name (e.g.,
tips_es_ES.txt). This new file is then listed as the translation for
tips.txt in Poedit. This is explained next.
The default Start-up Tips file (in US-English) is named
tips.txt and is located in the following directory
To create the same file for another language, do the following:
tips.txt to a new file
Rename the new file according to the
ll_CC convention (or possibly just
ll) consistent with the language you’re working on, whichever is appropriate (e.g.,
tips_zh_CN.txt for simplified Chinese, or
tips_ar_001.txt for Modern Standard Arabic)
Open the new, renamed file using your preferred text editor
Translate the English-language tips by replacing them entirely with those of the language you are working on
Apologies for stating the obvious, but it would be a good idea not to delete any English entry in the new
.txt file before you have completely translated it, or decided it is not appropriate. Rather, type in the relevant translation below the English entry first, and then delete the English entry only when the translation on the new line is complete.
Save your work
Find the string
Source text - English (the easiest way is
Edit > Find > Find: tips.txt)
Where you would normally provide a translation for it, simply provide the name of the new
.txt file that you just created. See the screenshot below for the case of Japanese.
Some of the humor in the Start-up tips might not translate well, so feel free to leave out things that would be too odd, or include occasional mild humor that would be more appropriate. Humor must be respectful and suitable for using in a classroom, laboratory, or other professional situation. Don’t get too creative here. If you have any doubt, it is better to leave it out. It goes without saying that you should avoid any religious, political, disrespectful, or sexist material.
Commit the files that you have changed
Usually, this is at least the
But it could also comprise or include other relevant files (e.g.,
The commit-message prefix for translations is always
DOCS: Swahili translations
Use the prefix
DOCS: in your commit message
Push the commit to your repository on GitHub (aka origin)
From origin on GitHub, make your pull request to the release branch of the PsychoPy® repository as outlined in how to contribute to PsychoPy
The default list of languages we have provided is clearly not exhaustive. (Current estimates on the number of languages in the world suggest that there are between 6,000 and 8,000 human languages in the world, depending on how you define language!) So you may indeed find it necessary to create a new directory containing the
.po file necessary to enable PsychoPy® to operate in the language you want to translate into.
If this is the case, feel free to add your language or language variety. Below is an explanation of the easiest way to do this, followed by finding the most appropriate label for your new subdirectory.
The easiest way to get started is to copy and paste one of the other
ll_CC directories, then rename it. Then you can make adjustments to the
messages.po file inside. How to do this is covered up above in the section called The translation process in Poedit.
The immediate question, however, is what to rename it to. This may require some forethought involving linguistic and cultural appropriateness.
ll_CC label you use, please be as inclusive as you possibly can, within reason. Naturally, you are the expert here since you actually know the language, its varieties, and any political implications involved. Make sure, however, that you are highly proficient in whichever one you choose.
If in doubt, please feel free to discuss this with the PsychoPy® team directly, or on the forum under the Development category. The same is true if you cannot find your language at all in the list of languages at Gettext: Please talk with the PsychoPy® team to find a solution.
Chinese is a good example of when locale matters a great deal. The simplest distinction is that Simplified Chinese characters are used in mainland China (
zh_CN), whereas traditional Chinese characters are used in Taiwan (
Most readers of Arabic are going to expect to see Modern Standard Arabic, which has the slightly odd
ll_CC code of
ar_001 as it is not the native dialect of any particular country. Spoken regional varieties of Arabic in the written form are only ever seen in specialized contexts.
Another example is English. The default variety of English for PsychoPy® is American English (
en_US). One could include a translation for British English (
en_GB), but the effort required of such a translation with such minor (mostly spelling) differences hardly seems worth it.
Return to The translation process in Poedit