Translation

Peter Mattern edited this page Aug 13, 2016 · 4 revisions

Overview

As of May 2016 the LXQt project is in transition to an approach involving Pootle, a web interface similar to the well-known Transifex.

For now potential translators have to take a not too convenient approach which involves dealing with local VCS (Git) checkouts of two kinds of repositories which correspond with two file types that have to be edited.
The so-called TS files like pcmanfm-qt_de.ts belong to the Qt Linguist framework and cover the translations of the actual GUIs. They are summarized in a dedicated repository lxqt-l10n.
Desktop entry files according to the Desktop Entry Specification like pcmanfm-qt.desktop are used to represent components in panel menus and the likes and are still comprised in particular components' repositories due to technical limitations.

This page depicts the general approach and the distinction between language and country specific translations which represents an important aspect translators need to bear in mind.

General approach

You need to have a GitHub account. Git should be available via CLI at your local system. To get accustomed to Git the Git book can be recommended as an excellent source.

TS files

  1. Prepare Git repositories
    • Fork repository lxqt-l10n into your GitHub account:
      Log into GitHub, open the repository's page and hit the corresponding button in the upper right.
    • Prepare a local copy: Clone a local copy of repository lxqt-l10n
      $ git clone https://github.com/lxde/lxqt-l10n.git
      Change into the directory created that way and complement the remote repositories with your own GitHub account
      $ git remote add foobar https://github.com/foobar/lxqt-l10n.git
      where foobar is your username on GitHub (note it has to be replaced two times). Update the local information
      $ git fetch --all --prune
      Create a branch to do the actual work like e. g.
      $ git checkout -b transl_comp_xx
      where "comp" has to be replaced by the component in question like lxqt-panel or pcmanfm-qt and "xx" by the code corresponding to the language like en, ar, fa or ru. Using a dedicated branch like this isn't mandatory but makes a lot of sense.
  2. Translate TS file(s): The files are summarized in folders named like the corresponding component, e. g. pcmanfm-qt, some of these folders are comprising sub-folders like the ones corresponding with the various plugins of lxqt-panel. The naming of files is covered in section Language vs. country specific translations.
    • Look for the directory in need and check whether the TS file of the translation in question, say pcmanfm-qt_de.ts, already exists. If the file doesn't exist yet, copy the template TS file like pcmanfm-qt.ts as needed.
    • Edit the TS file. While this can be done manually in any arbitrary text editor the use of Qt Linguist which is provided by all major Linux distributions is strongly recommended. Among other this tool indicates mistakes regarding the syntax of translations and gives an overview which strings have already been translated and which haven't. Also, a mockup of the majority of GUI objects which are translated is provided making the translation much easier.
  3. Sum up your work in a commit and upload.
    • Check whether Git is aware of all modified files
      $ git status
      This should output all files that were edited but no additional changes.
    • Make a commit
      $ git add . && git commit
      The latter will bring up an editor to file a commit message. Its first line should be a comprehensive summary of the work that was done. Separated by a blank line an optional, more verbose comment may be added. Limiting all these lines to 68 digits makes the text more readable in GitHub's web interface. Please adhere roughly to these recommendations.
      Instead of git commit you may run
      $ git commit -m <summary>
      (< > placeholder only) which allows for making the commit and filing its summary as stated above in one step and without using an editor but doesn't allow for adding a further comment.
    • Push the commit to your own repository
      $ git push --set-upstream foobar transl_comp_xx:transl_comp_xx
      You will need your GitHub credentials.
  4. Submit a Pull Request via GitHub's web interface.
  5. Addendum - editing existing commits: Maybe you need to fix an error or edit your work in some other way. This can be done as follows:
    • Edit the same way as depicted in step 2.
    • Amend a new commit to the preexisting one
      $ git status
      and if that's okay (see above)
      $ git add . && git commit --amend
      If more than one preexisting commit is involved you may rather squash commit(s) into previous ones.
      Either way you may or may not change the commit message. Not changing means to remove an additional blank line that's added to the preexisting comment automatically. Make sure that the number of commits is adequate. In particular the number of commits should never be larger than the number of modified files.
    • Push your changes to your own account
      $ git push --force foobar transl_comp_xx:transl_comp_xx
      This will automatically update an eventual PR as well.

Desktop entry files

As mentioned above these are still comprised in distinct components' repositories like the one of PCManFM-Qt where they reside in a folder translations. Translations are handled by snippets like pcmanfm-qt_de.desktop comprising nothing but the respective translation. In contrast to TS files the template normally isn't in directory translations as well but in its parent directory and suffixed by .in, see e. g. pcmanfm-qt.desktop.in.
The most reasonable way to edit desktop entry files is just an arbitrary text editor.

Considering these differences the proceeding is exactly the same as outlined for the TS files above.

Language vs. country specific translations

The Qt translation framework allows for distinguishing language from country specific translations which does have some implications that should get considered by translators.

Glossary

Language specific translations are meant to cover a language independently from a particular country. Corresponding files feature a single double-digit lower-case code referring to the language only like "pt" in lxqt-panel_pt.ts for Portuguese.
Country specific translations are meant to address a language variant that's spoken in a particular country only. Corresponding files feature an additional double-digit code in capital letters referring to a particular country like "BR" in lxqt-panel_pt_BR.ts for Brazil.

Either way the code(s) have to be reflected in the TS files' headers as well like
<TS version="2.1" language="pt">.
or
<TS version="2.1" language="pt_BR">
This can get handled by Qt Linguist, too (menu Edit - Translation File Settings).

Need for country specific translations

Frequently these aren't needed at all. E. g. German gets spoken in several countries and plenty of differences exist. But these do not affect the technical terms used by LXQt in any way.
In Portuguese many of the technical terms used by LXQt are different in Brazil or Portugal, though. Corresponding country specific variants are hence needed.

So first of all a translator should think about the need of country specific translations. Questions can be asked in the Pull Request's comment and be discussed with other native speakers.
If country specific translations aren't needed a single language specific translation like de will do (and the next paragraph doesn't matter any longer).

Country specific translations vs. system locale

The locale used by a running system as indicated by the output of $ locale on Linux will be country specific most of the time like in this example

$ locale 
LANG=de_DE.UTF-8
LC_CTYPE="de_DE.UTF-8"
LC_NUMERIC="de_DE.UTF-8"
[...]

Note the string de_*DE*. The encoding, usually UTF-8 nowadays, frequently ISO-8859-1 earlier, doesn't matter in this context.

It is important to note that country specific translations are only used when a system's locale is set to the same country.
E. g. a Portuguese translation pt_BR is only used when a running system's locale is pt_BR, too. This translation does not get used if the system's locale is pt_PT (Portugal).
This means that no Portuguese translation is used at all should a system's locale be set to pt_PT and pt_BR be the only Portuguese translation that's available.

Language specific files will always be used as fallback.
E. g. if two translations pt_BR and pt are available and a system's locale is set to pt_PT translation pt will be used.

As a consequence a country agnostic translation like pt should be provided even if country specific translations are basically needed as long as not all of them are available yet.
This should be done in order to have a fallback as depicted above. It's still better to use a translation that eventually doesn't fit the country of a running system's locale than no translation at all resulting in an English GUI.