The most common activity of the the MX translations coordinator is handling translations for the QT, Python, and shell script applications that have been prepared by MX developers. Other wiki articles describe how to handle special cases and do a complete refresh of translations. This article describes how to take one request for one app from beginning to end.
1. Get the app
- The developer notifies the coordinator that translations are required for a new or existing app.
- If it is an existing app, the coordinator goes to the directory on their PC where the repo for that app exists (say …/repos/mx-someapp) and does:
$ git pull
- Otherwise, if it is a new app, then the coordinator clones it from the GitHub repo:
Go to https://github.com
Log in using your GitHub account
Change the context to MX-Linux
Select the repository for the new app
Click “Clone or download”
Click the clipboard icon to copy the link
Log out of GitHub
Go to the directory on your PC you use to save MX app repos (say …/repos) and create the repository for the new app:
$ git clone the_link_you_copied
This creates a directory (say …/repos/mx-someapp) with all of the files pertaining to the app cloned from the GitHub MX-Linux repository.
- It’s a good idea to organize all your admin-related work related to each translation effort in separate directories outside of the …/repos hierarchy, e.g. for this task, …/jobs/001_mx-someapp. Use this to store emails, temporary files and directories, etc.
2. Create the English source translation file
Ensure you are in the repo’s directory on your PC:
$ cd …/repos/mx-someapp
For a QT app:
$ lupdate *.cpp *.h *.ui -ts qttext.ts
This extracts all the text from the QT source files for the app and puts them in one file – its name/location is not important, but here we’ve put it in the top level of the repo’s directory for convenience.
For a shell app:
$ xgettext -L Shell -o shelltext.po mx-someapp
… assuming mx-someapp is the name of the source script. If the app contains more than one script, just include them all on the command line. You may notice that some of the original text is split over two or more lines in the output file. That’s OK – Transifex will glue them back together and present them as one text string to the translator.
Instead of using xgettext to create the .po file, you could use an option of the bash command:
$ bash –dump-po-strings mx-someapp > shelltext.pot
But this produces a file not quite in the format Transifex expects. You would have to manually insert a few lines. See the file produced by xgettext for comparison.
For a Python app:
$ xgettext -L Python -o pytext.po mx-someapp
3. Check the English text in the translation file
- First, if this is a shell or Python app, then check the character coding used in the file just created. If it contains “charset=CHARSET“, change that to “charset=UTF-8“. This will ensure that foreign language characters are rendered correctly in transfers to and from Transifex.
- Then, for all types, check the English text strings in the file you produced. Any spelling/grammar mistakes? Ambiguities or something that could be expressed better? If so, resolve with the developer and do a git pull to get new changes.
4. Upload the translations
- Log in to your account on Transifex https://www.transifex.com and select the antix-development project if not automatically taken there.
- Click on Resources. The list of all antiX and MX translation resources is displayed.
- If you are uploading changes to an existing app, click on that app’s name, and when the app’s page is presented, click on the Update content button. Follow the prompts to select the file you created on your PC (qttext.ts, shelltext.po, pytext.po, or whatever the case may be).
- If you are uploading changes for a new app, then click on the Add resources button and follow the prompts. When you choose a name for the resource, don’t accept the Transifex-offered name. It will take a name like qttext.ts and suggest “qttextts” as the name of the resource. Instead, use the same name as the repo on your PC (eg mx-someapp), which is the MX app name, with no extension. Transifex should be able to figure out the correct type of the file – QT for .ts or po for .po (and in rare cases txt for .txt).
5. Create desktop entries if necessary
Most apps come with a desktop file. So if this is a new app, the Name and Comment entries for each language will need to be completed in the desktop file. The translations for these entries are done through a separate resource on Transifex, where the desktop entries for all apps are collected: mx-all-desktop-entries. Add the Name and Comment English values to this file with these steps:
- Download the English file for mx-all-desktop-entries.
- Using the values for Name and Comment in the repo’s .desktop file (which were set by the developer), add the corresponding entries to this downloaded file. Insert in the correct alphabetical order of Name, just for easy listing.
- Update the Transifex resource with this file.
6. Notify the translators
Although they will be automatically notified by Transifex of the new content (unless they have turned that setting off), the coordinator also makes a post in the MX translation forum. Use the “Request for translations thread”, or start a new thread if warranted. Make a post informing the translation team of the new content on Transifex and asking for their help. Give a link to the resource name. Let them know if it’s an urgent request. And, if it is a new app, request them to also update their language’s Name and Comment entries in the mx-all-desktop-entries resource.
7. Monitor progress
The coordinator checks the status of the Transifex resource periodically. If necessary, send private messages through the forum’s mail (or Transifex’s messaging facility) to translators who have yet to respond. Monitor the forum for questions and issues.
When translation is complete (or no more are expected) notify the developer that you wish to push the translations and get their OK.
8. Refresh your PC cloned directory
Before pushing the translations, make sure you have the latest version of the app.
$ cd …/repos/mx-someapp
$ git pull
If there are changes (affecting the source text), then it will be necessary to make a new upload to Transifex. If this results in untranslated strings there, then alert the translators by making a new MX forum post in that topic, and wait for the new strings to be translated on Transifex.
9. Download the translation files from the Transifex resource
There are several ways to do this.
If only a few languages are involved, use the Transifex website:
- Log on to Transifex
- Select the resource
- Select the first language
- In the pop-up, select “Download for use“
- Trim the suggested name, removing the leading “for_use_antix_development_”
- Save to your PC
- Repeat for all completed (or substantially completed) languages
If you need more than a few languages, Method 1 gets tedious fast. A script that takes advantage of the Transifex API can download all the languages at once. One such script is getmxtrans contained in the repository translation-tools of the MX-Linux context on GitHub. Once on your PC, it is used like this:
$ ./getmxtrans yourtxusername yourtxpassword Download from Transifex the translation files for a resource % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 20442 0 20442 0 0 23807 0 --:--:-- --:--:-- --:--:-- 23825 Number of resources 27 1 apt-notifier 15 mx-panel-orientation 2 ddm-mx 16 mx-remastercc 3 mx-all-desktop-entries 17 mx-repo-manager 4 mx-bootrepair 18 mx-select-sound 5 mx-broadcom-manager 19 mx-snapshot 6 mx-codecs 20 mx-switchuser 7 mx-compton 21 mx-system-sounds 8 mx-debian-backports-installer 22 mx-test-repo-installer 9 mx-defaultlook 23 mx-tools 10 mx-findshares 24 mx-usb-unmounter 11 mx-flash 25 mx-usb-unmounter-start 12 mx-installer 26 mx-user 13 mx-menu-editor 27 mx-welcome 14 mx-packageinstaller Resource number? 6 removing previous downloads in mx-codecs directory Downloading translations files for mx-codecs ... ca downloads/mx-codecs/mx-codecs_ca.ts https://www.transifex.com/api/2/project/antix-development/resource/mx-codecs/translation/ca/?file % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 8648 100 8648 0 0 15491 0 --:--:-- --:--:-- --:--:-- 15498 cs downloads/mx-codecs/mx-codecs_cs.ts https://www.transifex.com/api/2/project/antix-development/resource/mx-codecs/translation/cs/?file % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 8512 100 8512 0 0 15960 0 --:--:-- --:--:-- --:--:-- 15969 ...
Note that getmxtrans downloads a standard set of language files. Modify the script as necessary when new languages join the project.
These techniques work fine on the MX side as long as there are a relatively small number of resources. The antiX side uses a more automated process that can better handle a large number of resources. It would be worthwhile exploring further.
10. Transfer the translation files to your cloned repo
This step assumes you used the getmxtrans script to download a whole directory of translation files.
First delete the current translations directory in your repo: …/repos/mx-someapp/translations. In the case of a script app, this directory will be called …/repos/mx-someapp/translations_script.
Copy the directory you downloaded with getmxtrans into your repo and rename it translations (or translations_script as appropriate).
11. Make the translation object files
For a QT app:
As a rule, the MX translation co-ordinator doesn’t prepare the QT object files. Instead, it’s done by the app’s developer as part of their build process. However, here is the command to do it should it ever become necessary:
$ cd …/repos/mx-someapp/translations
$ lrelease mx-someapp_ca.ts -qm mx-someapp_ca.qm
$ lrelease mx-someapp_de.ts -qm mx-someapp_de.qm
It is also possible to do all languages at once using the .pro file as input.
For a shell or Python app:
You could make the .mo files individually using the msgfmt command. However, it is easier to use the makemofiles script found on GitHub in the translation-tools repository.
Copy the script makemofiles into the translations_script directory. When you run it there, it creates the object language files and places them in appropriate language sub-directories within the mo directory. Note that these object language files all have the identical name. It is their placement in separate language directories that distinguishes them.
12. Edit the .pro and .desktop files
For a QT app, the languages specified in the .pro file should all be present in the translations directory. Edit the .pro file to add or delete languages as required to make them match the contents of the translations directory. Sometimes the .pro file is named after the app, like mx-someapp.pro. Sometimes it is named src.pro.
If it’s a new QT app, you will need to add to the .desktop file the Name and Comment entries that have been translated in mx-all-desktop-entries. (And even for an existing QT app, there could still be additions as translators get around to them.) It would be tedious to extract the two Name and Comment lines from each of the many language files on Transifex. Instead, do this:
- Download all the language files for mx-all-desktop-entries using the getmxtrans script.
- You will need the English file as well. Since getmxtrans doesn’t (by design) download the English file for any Transifex resource, you will need to download it manually and place it in the same directory as the others (and give it the same sort of filename as the others, i.e. mx-all-desktop-entries_en.txt).
- Copy the resulting mx-all-desktop-entries directory from the …/tools/api/downloads directory to the same directory where the script remake_desktops (from the translation-tools repo) is located.
- Run that script from a terminal in its directory: ./remake_desktops.
- This will splice all the language files together into the file all.txt so that the translations are now grouped by app rather than by language.
- Open the all.txt file with a text editor and locate the section that contains the entries for the app you are dealing with.
- Paste the Name and Comment blocks for this app into the appropriate spots of the .desktop file in the cloned repo you are working with. Overwrite whatever Name and Comment entries happen to be there already.
13. Push the changes to the MX-Linux repo on GitHub
This is a 3-step process requiring add, commit, and push. But first, do a status to see what git thinks you have modified.
$ cd …/repos/mx-someapp
$ git status
Before proceeding, remove any extraneous working files you may have created that show up in the status. For example qttext.ts, etc.
For a QT app:
$ git add translations/mx-someapp_ca.ts
$ git add translations/mx-someapp_ca.qm
Or just add the whole directory at once:
$ git add translations/
Add the .pro and .desktop files if you edited them:
$ git add mx-someapp.pro
$ git add mx-someapp.desktop
For a shell or Python app:
$ git add translations_script/po/mx-someapp_ca.po
$ git add translations_script/mo/ca/mx-someapp.mo
$ git add translations_script/po/mx-someapp_de.po
$ git add translations_script/mo/de/mx-someapp.mo
Or just add the whole directory:
$ git add translations_script/
Then for all commit and push:
$ git commit -m “Translation changes for mx-someapp”
$ git push
Username for ‘https://github.com‘: yourGitHubusername
Password for ‘https://…@github.com‘: yourGitHUBpassword
Counting objects: 23, done.
Compressing objects: 100% (23/23), done.
Writing objects: 100% (23/23), 4.00 KiB | 0 bytes/s, done.
Total 23 (delta 21), reused 0 (delta 0)
remote: Resolving deltas: 100% (21/21), completed with 17 local objects.
6f191ee..d88a7ab master -> master
14. Save documents and update control files
Save material related to this job in the …/jobs/nnnn directory you set up when you started.
- Save the terminal log.
- Save mail, private messages from the MX forum.
It’s handy to have a small file containing the name of each app and the date its translations were last pushed to the MX-Linux repositories on GitHub. Update that.
Finally, if this is a new app, then you will want to make sure it is recorded in the files that drive the refresh process. (See the separate wiki translation article for how to carry out a refresh of the translations for all the MX resources.) This requires making a one-line entry in each of the files desktop_driver.txt and trans_driver.txt which are part of the mx-tools repo and should also be present on your PC as part of your initial set-up. Both files contain header comments that explain the required format of their entries.