Writing translations

From BATCOM-IT Services Wiki
Revision as of 09:22, 3 December 2015 by Admin (Talk | contribs) (We want maintained translations)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

A comprehensive guide for new QMC2 translators

Introduction

QMC2 has been designed with full multilingual capabilities from the beginning. So localizing QMC2 for a specific region or language is basically just a matter of the actual translation, but someone with proper (preferably native) knowledge of the respective language still has to do it.

We're thus always searching for QMC2 translators and people who want to support us qualifying & maintaining existing translations. If you are interested and want to get involved, feel free to do so and contact us!

Be aware, though, that doing a new translation from scratch probably means a little learning curve regarding Qt's internationalization tools (mainly Qt Linguist) in case you haven't worked with them before, and surely is a remarkable amount of work initially. However, once this is done, all later regular updates shouldn't be too heavy.

Also, being familiar with basic Subversion (SVN) commands wouldn't hurt. But we're explaining most of the few commands required in this article anyway, so it's no show stopper if you don't know anything about SVN or version control in general.

We want maintained translations

We appreciate any type of contribution, be it just a singular patch or more than that, but we prefer a long-term commitment, especially when you would like to take over the maintainer-job for a translation. Translations are no static thing, they require regular updates as the project evolves, and again someone to take care of this!

The current status of the existing translations is as follows (sorted by language code):

  • German (de): maintained by René Reucher: up to date, no support required
  • Greek (el): maintained by Kostas Albanidis: nothing yet, new maintainer required
  • Spanish (es): maintained by Daniel Barrado: mostly up to date, no support required
  • French (fr): maintained by Yû Voskoboinikov: being updated, no support required
  • Italian (it): maintained by Stefano Cereda: mostly outdated, new maintainer required
  • Polish (pl): maintained by Julian Sikorski: mostly outdated, new maintainer required
  • Portuguese (pt): maintained by Marcelo Bossoni: up to date, support welcome
  • Romanian (ro): maintained by Mihai Boisteanu: mostly up to date, no support required
  • Swedish (sv): maintained by Daniel Nylander: mostly outdated, new maintainer required
  • English (us): maintained by René Reucher: up to date, no support required

Feel free to add your language here or support improving existing translations, and join the team!

What has to be translated?

Not counting the documentation and category.ini (which can both be translated, too), the steps to translate QMC2 basically consist of 2 things:

  • Translation of strings in the application(s) itself using Qt Linguist. We deeply apologize in advance for the sheer amount of translatable strings that are already existing -- last time we counted there were over 4000 of them in QMC2's main GUI, plus several hundreds for the rest (QMC2 Arcade and Qt CHDMAN GUI). Not scared off yet? Good!
  • Translation of <section> and <option> elements in application-external emulator configuration templates (XML files) that are available for every supported emulator. There's a Java / SWT based template editor made by Marcelo Bossoni as part of the QMC2 source tree which you can use for this job (recommended), or you can edit these files manually with a POSIX-compliant editor of your choice (not recommended).

It's probably a good idea to start with the application translation using Qt Linguist as this is supposed to be the easier and more important part, then do the template translation in a second step.

General rules and requirements

Requirements for all translation maintainers (not for one-time contributors):

General rules:

  • When using an editor for any manual editing of text-files (or a tool of some sort to do this job), please make sure that it produces POSIX-compliant line-endings (0x0A / LF) and not WinDOS-typical ^M's (0x0D 0x0A / CR LF)! QMC2 is a multi-platform application, but the main development platform is Linux, and we simply don't want that sort of source code pollution from a non-POSIX platform. If you feel unsure what this is all about, please see here and here.
  • Source code pollution is generally something we don't want to see :).
  • Please only change files that are part of your project role(s), that is, when your role is to maintain a specific translation, edit only the files that are related to it and nothing else. When you have multiple roles in the project you can do whatever else they may account to, of course.
  • Locking of files in the SVN repository should be avoided. In cases where this may really be necessary, please inform about the step and its reason via the development mailing-list!
  • Especially when you're busily working on a new translation, it's better to do many small than just a few big updates (commits to the SVN repository), even several times a day if that's applicable.

QMC2 vs. Qt translations

Qt comes with a number of translations for the library itself, for things like standard file- or input-dialogs. So besides the application-specific (QMC2) translations there are also ones for Qt, and QMC2 even redistributes them (just in case). The application will actually activate two translators (QTranslator instances) when it starts up, one for QMC2's translations and a second one for Qt. It will try to load the compiled translation files (<DataDirectory>/lng/qmc2_<lang>.qm and <DataDirectory>/lng/qt_<lang>.qm), but when one or both of them can't be found or loaded, the translator(s) will produce English fall back texts instead.

Unfortunately, the number of available Qt translations is still fairly limited, so it can happen that parts of the application's UI experience are displayed in English, while other parts (the majority) is shown in the translated way. That's a situation we can't really change other than doing the necessary translations ourselves or helping / pushing others to do it. There are a few community efforts trying to fill that gap, but official Qt translations are a bit rare, to be honest. Well, Qt is open source, so perhaps you would also like to get part of the Qt Project and maintain a (new) official Qt translation directly.

Anyway, the fall back to English will always work, so functionality should never be affected.

How's the work flow organized?

Before you can start translating, the project maintainer has to prepare a number of things in the SVN source tree to make the new language available to the application. One of these preparations is to produce new virginal language files like data/lng/qmc2_<lang>.ts (translation source) and data/lng/qmc2_<lang>.qm (compiled translation). You'll work on the translation sources primarily later.

You can then start working by checking out the latest code revision from the SVN repository:

rene@thunder:~> mkdir ~/src; cd ~/src
rene@thunder:~/src> svn co --username <user> svn+ssh://<user>@svn.code.sf.net/p/qmc2/code/trunk qmc2-svn
...
Checked out revision 4632.

Side note:

  • The SVN traffic is tunneled through SSH, which also means that there are two levels of authentication. The SVN password can be stored locally, however, the SSH password usually can't. As a result you will have to enter its password every time the SVN client talks to the server. However, public key exchange solves this, and so the easiest way to get rid of the annoying SSH password prompts is to upload your public RSA or DSA key(s) at this URL: https://sourceforge.net/auth/shell_services

This is the list of translation source files eligible for translation:

rene@thunder:~/src> cd qmc2-svn
rene@thunder:~/src/qmc2-svn> find . -name "*.ts" | grep -v qt | sort
./arcade/translations/qmc2-arcade_de.ts
./arcade/translations/qmc2-arcade_el.ts
./arcade/translations/qmc2-arcade_es.ts
./arcade/translations/qmc2-arcade_fr.ts
./arcade/translations/qmc2-arcade_it.ts
./arcade/translations/qmc2-arcade_pl.ts
./arcade/translations/qmc2-arcade_pt.ts
./arcade/translations/qmc2-arcade_ro.ts
./arcade/translations/qmc2-arcade_sv.ts
./arcade/translations/qmc2-arcade_us.ts
./data/lng/qmc2_de.ts
./data/lng/qmc2_el.ts
./data/lng/qmc2_es.ts
./data/lng/qmc2_fr.ts
./data/lng/qmc2_it.ts
./data/lng/qmc2_pl.ts
./data/lng/qmc2_pt.ts
./data/lng/qmc2_ro.ts
./data/lng/qmc2_sv.ts
./data/lng/qmc2_us.ts
./tools/qchdman/translations/qchdman_de.ts
./tools/qchdman/translations/qchdman_el.ts
./tools/qchdman/translations/qchdman_es.ts
./tools/qchdman/translations/qchdman_fr.ts
./tools/qchdman/translations/qchdman_it.ts
./tools/qchdman/translations/qchdman_pl.ts
./tools/qchdman/translations/qchdman_pt.ts
./tools/qchdman/translations/qchdman_ro.ts
./tools/qchdman/translations/qchdman_sv.ts
./tools/qchdman/translations/qchdman_us.ts

To update your local copy with changes committed by others, just run this:

rene@thunder:~/src/qmc2-svn> svn update
...
Updated to revision 4633.

It's recommended to do an update at least every time before you start your (daily) work.

You'll then work on the translation as described below, and when you're done with your work, you'll commit your changes to the repository:

rene@thunder:~/src/qmc2-svn> svn commit -m "German translation update"
...
Committed revision 4634.

Now, that's the usual simple process, but creating a new translation from scratch will surely take quite a bit of time to reach completeness, so we've set up a few reasonable rules for such periods in order to avoid possible SVN merge-conflicts:

  • The project developers refrain from running 'lupdate' as long as possible.
  • Whenever there's a must to run 'lupdate', a message will be posted on the mailing-list asking busy translators to commit their changes as soon as possible and to offer a short GO info in response, so developers could run 'lupdate' safely afterwards and reply back with a done mail so translators know they can resume their work (after having run svn update, of course).

Also, when a new release is soon to be made, the project maintainer will send a request for last-minute translation updates message to the development mailing-list a few days before its expected due date (which is sometimes hard to guess since QMC2's release schedule follows MAME's one... however, we're meanwhile usually informed early enough about upcoming MAME releases, so this shouldn't be an issue anymore).

Translating the QMC2 application

Translation of the QMC2 application is done with the official Qt internationalization tools, and in particular with Qt Linguist as far as the job of a translator is concerned.

We're not going into it here, but recommend reading the official Qt Linguist documentation in case you're not yet familiar with it. It also explains some of the basic concepts of the translation process.

Here's an example of how it looks like when working on a more or less unfinished (or new) translation:

Qt Linguist

Translating emulator configuration templates

In QMC2, all available (or known) emulator configuration options -- command-line arguments or ini-settings -- of every supported emulator are stored in external XML files which you'll find as data/opt/<emulator>/template.xml within the source tree.

The basic idea with regard to translation is quite simple: every <section> and every <option> can have translations of their <description>'s.

Example:

<?xml version="1.0"?>
<template emulator="MAME" version="0.153" format="0.2.7">
...
  <section name="search_paths">
    <description lang="us" text="Search paths"/>
    <description lang="de" text="Suchpfade"/>
    ...
    <option name="crosshairpath" type="directory" default="crosshair">
      <description lang="us" text="Path to crosshair files"/>
      <description lang="de" text="Suchpfad für Fadenkreuz-Dateien"/>
      ...
    </option>
  </section>
  ...
</template>

A <description> element can be supplied for every language (see the lang attribute), and the value of its text attribute is the translation of the respective element (<section> or <option>). When a translation is missing for the currently selected language, the native description (lang="us") will be used instead. So automatic fall back to English also works here.

You could edit those files manually with a text-editor of your choice (note again that the editor must be POSIX-compliant). However, syntax errors in the XML templates could actually lead to serious troubles, so we do not recommend to translate them this way in case you're not yet familiar with the expected format (the parser makes a number of assumptions and is not very fail-safe, to be honest).

Fortunately, we also have a tool for this -- a Java / SWT based template translator made by Marcelo Bossoni -- which will make your life a lot easier, will be less prone to mistakes and is thus recommended:

Java / SWT based QMC2 template translator by Marcelo Bossoni

It can be found in the tools/qmc2_options_editor_java/ folder within the source tree.

Translating the documentation

Language-specific documentation folders can be created for every available translation below the data/doc/html/ folder (the images sub-folder is for shared images):

rene@thunder:~/src/qmc2> ls data/doc/html/
de  images  us

If a language-specific folder doesn't exist and/or doesn't contain an index.html file, QMC2 will automatically fall back to the US English version of the documentation.

As already mentioned above, translation of the documentation is completely optional. It's not something we expect from anyone, and there has actually not been a single serious effort for any of the available languages yet (with the exception of a few files, namely the German versions of CREDITS and INDEX).

If you still would like to translate the doc-files it'd be greatly appreciated! You would then need to add a folder for your language and place at least a translated version of index.html in it (best would be to add translated versions of all the original HTML files from the data/doc/html/us/ folder, of course).

Regarding the tools to use for editing your translated versions of the HTML files, it's more or less up to you. Any HTML editor should do fine, but the original documents were all made with just a text-editor -- hand-crafted vi-powered HTML :).

The built-in web-browser is even capable of JavaScript, so if you think you could pep up the documentation by the use of JavaScript in your translated files, you're basically free to do so, though it's in your responsibility to check its functionality/correctness. Browser plug-ins are also supported, but as they are platform- and system-dependent, you should not expect them to exist.

Also, once a translated documentation has been created for your language, it's in your responsibility to keep it up-to-date.

Translating machine categories

Machine categories are stored in data/cat/category.ini and we recommend that you provide translations to your language for the category names as well. Example:

...
[Satellite Receiver]
tr[de]=Satelliten Empfänger
tr[pt]=Receptor via satélite
tr[es]=Receptor via satélite
...

Simply add a line with your translation (tr[<language>]=<translation>) after the last available translation and do this for each category. If a translation to the current language doesn't exist, the English / native description (i. e. Satellite Receiver in this example) will be used as a fallback - so technically this is completely optional.

There is no tool to assist you in that other than any POSIX-compliant text editor. Either add your translations in place and commit the changes to SVN (provided you have write access), or send a diff (svn diff data/cat/category.ini) or a modified version of category.ini via mail / a forum post / whatever. Also, whenever a new category is added to category.ini we ask our users to provide translations in this forum thread (thanks to all who did in the past!), so that's another option to support us.

Links

Version Control with Subversion