QtInternationalizationOld

Latest revision as of 09:29, 16 May 2011

MAY 9, 2011: THIS IS AN OUTDATED DOCUMENT THAT IS NOT THE WAY L10N IS DONE FOR MEEGO. PLEASE SEE: Internationalization

Purpose

The goal of this document is to educate translators to use QtCreator and Linguist with the Qt/MTF-based MeeGo reference applications that have followed the MeeGo Internationalization wiki. This will not apply to all applications or libraries. The need for these steps is driven by the recommended steps for internationalization of the Qt/MTF-based MeeGo Reference Applications. Please read those instructions for any necessary context or explanation as to why it is the way it is.

As of the writing of this HOWTO (Septemper 22, 2010) the list of applications with translation projects already created include:

• meego-handset-music-translations
• meego-handset-sms-translations
• meego-handset-dialer-translations
• fennec-qt-translations
• meego-handset-chat-translations
• meegotouchcp-chat-translations
• meego-handset-socialweb-translations
• meegotouchcp-socialweb-translations

Assumptions

This process assumes the following environment will be used to perform translations:

• The project to be translated is structured according to the Internationalization wiki
• Translation is happening on a Linux OS (MeeGo and Ubuntu were tested, Fedora should work too)
• QtCreator package is installed
• Linguist package is installed
• The xdg-utils package is installed
• Git package is installed

It is also assumed that the translator is:

• Completely familiar with Linquist. It is beyond the scope of this document to help with the use of Linquist.
• Familiar with Linux-based OSes and how to install packages into the Linux OS they are using
• Familiar in principle with the basic concepts of Version Control Systems, in particular, Git.
• Has the necessary accounts and rights to push changes to source trees for translations hosted on gitorious.org

Finally, it is assumed that once Transifex has support for Qt projects and Linguist, this process will become obsolete and all further translations will occur through Transifex.

Process Summary

The basic process, detailed below is:

1. Customize QtCreator to launch Linguist
2. Check out project sources (read-only) to provide code context. This step is optional, but recommended
3. Check out project translations (read-write)
4. Make changes to .ts files
5. Publish updated translations back to upstream translation project

Set External Editor

1. Start QtCreator
2. Select "Options..." from the "Tools" menu:

1. Select "Environment" -> "General" option
2. Change the value of "External Editor:" as follows:
   1. Erase the default setting (can be restored by clicking the "Back Arrow" button to the right)
   2. Type in "xdg-open %f"
      • Assumes you have the xdg-utils package installed
      •  %f will be replaced with the file name to be opened
   3. Click "OK"

Clone Project Source

For Qt/MTF-based projects that used the MeeGo Internationalization wiki to prepare their code for translation, you must first clone the base project sources if you want Linguist to be able to load the code in the context pane while translating.

• Start QtCreator (if not already running)
• Select "New File or Project" from the "File" menu:

• Select "Git Repository Clone"

• Click "OK"
• Set clone options as follows:
  • Clone URL example: git://gitorious.org/meego-handset-ux/meego-handset-dialer.git
  • NOTE: We are using the "git" protocol here since we really do not want to be able to push changes to this project. It is only being cloned for contextual reference
  • Checkout Directory: meego-handset-dialer
  • Path: ~/dev/translations/

• Click "Next"
• Click "Finish"

You will now have a new project opened that is cloned from the upstream sources. For translation purposes, there is never any need to edit any of these files, so for simplicity sake, and to avoid confusion, it would be safest to close this project now.

Clone Project Translations

Now you must open a new project that is a clone of the above projects' translation sources.

• Start QtCreator (if not already running)
• Select "New File or Project" from the "File" menu:

• Select "Git Repository Clone"

• Click "OK"
• Set clone options as follows:
  • Clone URL example: git@gitorious.org:meego-handset-ux/meego-handset-dialer-translations.git

  NOTE: We are using the "ssh" protocol here since we do want to be able to push changes to this project.

  • This assumes you've properly configured your local system's git configuration to work with gitorious.org and the SSH key-based authentication (this is beyond the scope of this document).

  • Checkout Directory: meego-handset-dialer-translations
  • Path: ~/dev/translations/

File:QtCreator-New-Git-Clone-Options-2.png

• Click "Next"
• Click "Finish"

You are now using the new project for the translations you want to work on. To see the list of files in QtCreator, change the "Projects" pane to "File System" and you will see the list of .ts files available to work on.

Now let's get to editing and saving your work.

Edit a Translation File

• Open the .ts file to work on (double-click its entry in the "File System" list)
• Open a file in the (previously configured) external editor by selecting "Open in External Editor" from the "Edit" -> "Advanced" menu:

  Alternatively, press <alt-v><alt-i> on the keyboard

• Linguist should now launch, with the file opened above loaded and ready for translation.

• Begin your translation work and proceed to #Publish Changes when ready to save and push your changes to the upstream translation project.

Publish Changes

Sync Changes to QtCreator

Now that you have completed a set of changes, you must save them and re-sync QtCreator to be aware the file has changed.

• Select "Save" (or "Exit") from the "File" menu to save your changes (and, optionally, exit Linguist)
• QtCreator will notice that the file has changed and ask if you want to reload the changes:

• Select "Yes"
• You should now see the changes reflected in the source view panel in QtCreator.

Commit Changes to GIT

Assuming you want to keep these changes, you must "commit" them to your local clone of the translation git tree:

• Select "Commit" from the "Tool" -> "Git" menu:

• Provide details about the changes you are about to commit:

  Commit Information:

  Please use your Full Name and valid email address

  Description:

  A complete and detailed description is best, though for initial translations, simply stating so is enough

  Files:

  Don't forget to "check" the file(s) in the list that are associated with the above set of changes. If you do not, changes to files not "checked" will not get published!

• Click "Commit"

• Confirm the commit (un-check the "Prompt to Submit" if you want to avoid this dialog in the future):

Push Commits Upstream

Finally, in order for these changes to be visible to others, especially those responsible for packaging new versions, you must "push" (publish) them back to the upstream git tree

• • Select "Push" from the "Tool" -> "Git" menu:

NOTE: The process for getting updated translations packaged and published in the MeeGo RPM repos is beyond the scope of this document.