To be efficient, translators should follow a certain sequence of steps
We will now cover how to do this
Step 1: Identifying the appropriate 5-6 character ll_CC locale name for your translation
Step 2: Configuring the mappings.txt file with a text editor
Step 3: Working on main translations with Poedit
configure Poedit
generate and translate the “strings” in the messages.po file
Step 4: Translating “Start-up tips” in PsychoPy® with a text editor
NOTE: Steps 3 and 4 aren’t sequential; they’re different translation processes
ll_CC locale name for my language?¶First, we need to discuss how locale names work
Look under this directory in your local copy
psychopy/psychopy/app/locale
ll_ (language), followed by _CC (country), for example:
ar_001 for Modern Standard Arabic*
he_IL for Hebrew in Israel
tr_TR for Turkish in Turkey
fa_IR for Farsi in Iran
* This is the official locale for MSA. Let’s just hope the _001 code works in PsychoPy®. If not, we can switch to country codes (e.g., ar_EG for Arabic in Egypt)
ca_ES for Catalonian/Valencian in Spain
de_DE for German in Germany (hochdeutsch)
et_EE for Estonian in Estonia
fr_FR for French in France
hi_IN for Hindi in India
it_IT for Italian in Italy
lv_LV for Latvian in Latvia
nl_BE for Flemish in Belgium
pl_PL for Polish in Poland
pt_PT for Portuguese in Portugal
ru_RU for Russian in Russia
Recommendation
decide on which variety to start with
finish the translations for that variety of the language
copy, paste, rename, and adjust
ll_CC folder/file structure¶The file translators only work on
a messages.po file
located two levels under under any particular ll_CC folder for that locale
For example for Farsi (Persian) in Iran:
psychopy/psychopy/app/locale/...
NOTE: Ignore the intermediate LC_MESSAGE level, as well as the messages.mo file underneath
Look under psychopy/psychopy/app/locale
Is your ll_CC folder there?
may already be there
or not
if not, why isn’t it pre-listed?
unnecessary storage
pre-listing every language-country pair
storage waste
current list
just guesses
if not pre-listed, just add it
the easy way
find any ll_CC folder
ideally, look for a small .po file with no translations yet
copy and paste the entire folder
rename the folder to the ll_CC appropriate for your locale
make adjustments to the messages.po file underneath (covered soon)
the hard way
not a reasonable approach; not going there
mappings.txt¶Do this once per translated language, and it’s done forever (for that localisation)
This file allows the experimenter to choose a localization in PsychoPy®
Start your preferred text editor (e.g., Visual Studio Code, PyCharm, TextEdit [Mac])
Avoid using Notepad in Microsoft Windows
Use Notepad Plus instead
ll_CC code¶Open the following file (there’s one and only one)
/psychopy/psychopy/app/localization/mappings.txt
Is the ll_CC code listed?
Make sure the ll_CC code resides at the appropriate line (alphabetically listed)
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 Identifiers and and Locales.
NOTE: If you can’t find your language for some reason, just add a random three-letter sequence that isn’t already in use and probably doesn’t refer to a language (e.g., JJY). That should work.
At the far right,
type in the language and variety in that language
followed (in parentheses) by the the name of the language and variety, in English
do not include the variety (the part after the comma) if there is only one variety that anyone would ever use
for example
“español, España (Spanish, Spain)”
(not just “Spanish”)
“עִברִית (Hebrew)”
(not just “Hebrew”)
Save the mappings.txt file
mappings.txt¶Select psychopy under the tab labeled Current Repository
Select release under the tab labeled Current Branch
Stage the mappings.txt file (only)
go to the tab labeled Changes
make sure that mappings.txt is the only file with a checkmark
add the following message to the box underneath with the temporary text Summary (required)
DOCS: Update mappings.txt for Hebrew in Israel (for example)
this must be 50 characters or fewer
add extra information under Description, if necessary
click the box underneath labeled Commit to release
NOTE: If it’s not labeled Commit to release, start at the top of this slide again
click the
Push origintab
On GitHub (origin [AKA your online “fork”])
Click Contribute
Choose Open pull request
Leave a comment only if you think it’s necessary (it shouldn’t be for translations)
Click Create pull request
FINISHED!! (with mappings.txt)
Poedit
where most of your work will be focused
first need to set some things up
Sync from upstream to origin
Pull from origin
Again??!!
Yes
Do this every time you start work on a translation
Another translator may have changed the translation (the .po file) since the last time you worked on it
Go back to the end of Setting up version control for instructions
General settings¶Start Poedit
Once set, the settings below in Poedit don’t really change
General tab (Name and email)¶choose the following:
File > Preferences (on a PC)
Poedit > Settings (on a Mac)
Find the following tab: General
For convenience, make sure that the box with the following label is UN-checked:
Automatically compile MO file when saving
(Note that this is not strictly necessary as we have set Git to ignore the .mo file, but compiling this file is unnecessary and takes up processing time)
Do not provide your name or email
Doing so will list your name and email in a public place (GitHub), where it doesn’t really need to be
Instead, just leave these fields blank
Advanced settings¶click the Advanced tab in the same window
Make sure that the following are set correctly
Line endings:
set to Unix (recommended)
Preserve formatting of existing files
make sure this is checked
.po file¶First, open the .po file
File > Open
find the .po file for the language you’re working on:
.../psychopy/psychopy/app/locale/[your ll_CC folder]/LC_MESSAGES/messages.po
For example, for Thai in Thailand:
psychopy/app/locale/th_TH/LC_MESSAGES/messages.po
Go to: Translation > Properties
under: Language team (if there is more than one translator for the locale, and we have set up a Google Group for your team)
make sure that the email for entire group is correct
psychopy_[language]@opensciencetools.org
e.g., psychopy_hebrew@opensciencetools.org
under: Language
select the appropriate Language (Country) combination
For example
Duala (Cameroon)
under Charset
UTF-8 (recommended)
under the tab labeled: Sources Paths
For Base path
Click the arrow on the right
find the path on your computer that leads to the psychopy directory within the cloned repository on your computer:
..THE/PATH/ON/YOUR/COMPUTER/TO/psychopy/psychopy
NOTE: This setting does not make its way into the .po file. Rather, it’s just part of Poedit.
under the tab labeled: Sources Paths…
in the box labeled: Paths…
there should be a dot (.)
under the tab labeled: Sources Keywords
Go to: Additional keywords
The following keyword should be in that box (with the preceding underscore):
_translate
If it isn’t, type it in
Save your work (File > Save)
The elements you can translate are called strings
This process is straightforward if you are the sole translator on the language
But translation teams can run into merge conflicts
In such cases, make sure that you reduce the chances of merge conflicts by doing the following
synchronise your repositories
establish a team strategy (covered after the next slide)
Choose: Translation > Update from Source Code
You should subsequently see a list of strings in English that need translating into your language
If you don’t, the keyword _translate may not have been added to the keywords (see above)
NOTE: If Update from Source Code is greyed out, there are probably no new strings to update
This is for collaboration in a team, after the strings are updated
Choose: View > Show String ID
Choose: View > Sort by File Order
If you do both of those, then the strings will be listed in order by index
The index ID can be seen in the column at the far right
Teams can divide up the work by ID ranges, for example
Translator A: IDs 1-250
Translator B: IDs 251-500
etc.
Look at the list under the heading: Source Text - English at the upper left
Select a string that you want to translate
Once selected, you should see it appear as English in the following box below the longer list: Source text (at the lower left)
Below that, there is a box labeled as follows: Translation
Type your translation into that box
Save your work as you go
messages.po¶This involves several steps, described next
Select psychopy under the tab labeled Current Repository
Select release under the tab labeled Current Branch
Stage the messages.po file (only)
go to the tab labeled Changes
make sure that messages.po is the only file with a checkmark
if the .mo file is checked, UN-check it
add the following message to the box underneath with the temporary text Summary (required)
DOCS: Add translations to Modern Standard Arabic (for example)
DOCS: Add translations to Simplified Chinese (another example)
(again, must be 50 characters or fewer; add extra information under Description, if necessary)
(ignore the box labeled Description for now)
click the box underneath labeled Commit to release
NOTE: If it’s not labeled Commit to release, start at the top of this slide again
click the Push origin tab
On GitHub (origin [AKA your online “fork”])
Click Compare & pull request
Make sure it says Able to merge in the box at the top
Leave a comment only if you think it’s necessary (it shouldn’t be for translations)
Click Create pull request
Technical terms should not be translated:
Builder
Coder
PsychoPy
Flow
Routine
and so on
These are usually indicated with an uppercase first letter
Check the Japanese localization (ja_JP/LC_MESSAGES/messages.po) if in doubt
The Simplified Chinese .po file also has some examples
If there are formatting arguments in the original string (%s, %(first)i)
The same number of arguments must also appear in the translation*
If they are named (e.g., %(first)i)
(here, first is a python name)
that part should not be translated
Again, refer to the Japanese localization if in doubt
(and/or Simplified Chinese, if you are in that language)
* Word order changes across languages, of course. So the placement of these formatting arguments within the translated string may differ from the US-English string.
.po file for guidance¶The Japanese translation is nearly complete
You have it since you forked and cloned the repository
Open:
/psychopy/app/locale/ja_JP/LC_MESSAGES/messages.po
Look up the string you’re having difficulty with in the Japanese messages.po file
Use that as a model for your own .po file
(and/or Simplified Chinese, if you are in that language)
If you think your translation might have room for improvement
toggle the button labeled as follows: Needs Work
It should be located to the right of the header with the following label: Translation
You can also add notes to clarify
Click the button with the following label: Add Comment
This should be located at lower-right of the app window if you have the sidebar visible
Add your notes for that string into the pop-up window
Go to the PsychoPy Forum
There are friendly, useful experts there
When posting
select Development under Category
add the tag translation
How people on the Forum might help you
Few, if any, can help you with your language, of course
Many more who can help you understand the underlying code of PsychoPy®
NOTE: You need to understand Python quite well to take the following approach
Select the relevant string in the following box: Source text - English
Right-click the string (control-click on a Mac)
At the bottom of the pop-up window, you should see the following heading: Code Occurrences
Below that, you will see the (partial) path(s) to the file(s), followed by a colon, :, then the respective line number in the file
For example, for the string Yes in one version of PsychoPy®:
../app/connections/update.py:232 (meaning line 232 in the update.py file under the connections folder)
../app/dialogues.py:51 (meaning line 51 in the dialogues.py file under the app folder)
../app/dialogues.py:71 (etc.)
You can then go into that file (or those files) to determine the function
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
If you see fit to do so, toggle Needs Work and add a comment (see above)
Start-up tips are not handled directly in a .po file
Rather, they are stored in a .txt file, one per language
That .txt file is then referred to inside the .po file for your language
This is explained next
tips.txt to a new file¶Find the default Start-up Tips (in English) file
psychopy/app/Resources/tips.txt
Copy it
Paste it as a new file (tips copy.txt, perhaps)
Rename it according to the ll_CC convention consistent with the language you’re working on
For Example
tips_zh_CN.txt (simplified Chinese)
tips_ar_001.txt (Modern Standard Arabic)
Open the new, renamed tips_ll_CC.txt file using your preferred text editor (as long as it opens up the file with each tip on a new line, unlike older versions of Notepad)
Translate the English-language tips by replacing them entirely with those of the language you are working on
WARNING: Do not delete any English entry in the new .txt file before you have completely translated it. Instead, insert the relevant translation below the English entry. Then (and only then) delete the English entry. Save your work, of course.
.txt files as strings in Poedit¶Open Poedit
Find the tips.txt string under the following heading: Source text - English
Simply provide the name of the new .txt file that you just created as the translation for tips.txt
Naturally, this would be under the following heading: Translation - [your language]
For example:
|
|
|---|---|
|
|
.po and .txt files¶There are two files this time
Select psychopy under the tab labeled Current Repository
Select release under the tab labeled Current Branch
Stage both the messages.po and the tips_[ll_CC].txt file (e.g., tips_tr_TR.txt for Turkish)
go to the tab labeled Changes
make sure that the following two files are checked
messages.po
tips_tr_TR.txt (using Turkish in Turkey as the example)
IMPORTANT: Again, be sure to UN-check the .mo file if it is checked.
Commit these changes
add the following message to the box underneath with the temporary text Summary (required)
DOCS: Add some startup tips to Spanish in Mexico (for example)
must be 50 characters or fewer
add extra information under Description, if necessary
click the box underneath labeled Commit to release
NOTE: If it’s not labeled Commit to release, start at the top of this slide again
click the Push origin tab
On GitHub (origin [AKA your online “fork”])
Click Contribute
Choose Open pull request
Make sure it says Able to merge in the box at the top
Leave a comment only if you think it’s necessary (it shouldn’t be for translations)
Click Create pull request
Some of the humor in the Start-up tips might not translate well
Feel free to delete humor that would be too odd
or replace them with 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
More details on More information on Git workflow