Wiki Table of Contents

MX translations coordinator – handling apps

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.

Method 1

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

Method 2

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.

Method 3

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.
    To https://github.com/MX-Linux/mx-someapp.git
        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.

Leave a Comment

Do NOT follow this link or you will be banned from the site!