Devel Manual:Translate KLatexFormula

From KLFWiki

Contents 1 Translating KLatexFormula with Qt linguist 2 Compatibility with Prior Versions of KLatexFormula 3 Texts not Translatable with Qt linguist 3.1 Translating the "About" dialog 3.2 Translating the "What's New" dialog 3.3 Translating the Command-Line Help Text 4 Building a Translation Add-On

Translating KLatexFormula with Qt linguist

KLatexFormula uses Qt4's translation system with the linguist application.

Please refer to Qt's translator's manual to using linguist for basic and advanced linguist usage.

The translation process works the following way:

• create a translation source file (TS file) (if needed)
• if you already have a translation source file (eg. from previous version), make sure the messages to translate it contains are up to date
• translate the texts using Qt Linguist
• release the translation as a QM file
• package your translation to an KLatexFormula Add-On to profit to other users!

Make sure first you download the latest version of KLatexFormula (at least 3.2.4). A perl script is available to update the TS files correctly.

All files relative to translations are in the src/i18n/ directory in the klatexformula sources. All commands described here are to be run in that directory.

To create an up-to-date translation source file, or to update an existing translation file, run the klatexformula translations update tool:

./i18nupdate.pl klf_XX.ts

where XX is the 2-letter code for your language.

At this point, you can translate all the messages with Qt Linguist. Once you're done, select File->Release to create the QM translation file, or alternatively you can run manually:

lrelease klf_XX.ts

which will create the file klf_XX.qm.

Compatibility with Prior Versions of KLatexFormula

The i18nupdate.pl script provided in the source tree generates .ts files that are still fully compatible with previous versions of KLatexFormula since 3.0, by keeping obsolete texts and their translations (i.e., texts that have been removed or edited in more recent versions of KLatexFormula).

This way, a translation developed for version 3.2 can be used in version 3.1 normally.

If you are a translator, and do not wish to translate all the obsolete texts, simply run the update script with the --noobsolete option:

./i18nupdate --noobsolete klf_XX.ts

Texts not Translatable with Qt linguist

Some texts in KLatexFormula, for example the "About" dialog, cannot be translated with Qt linguist, since the displayed text is read from a configuration file since version 3.2.

Such texts include:

• The "About" dialog
• The "What's New in this version" dialog
• Help text provided with the --help command line option

Translating the "About" dialog

The About dialog can be translated by providing a file named about_XX.html, included into the translation add-on in a subdirectory named data. For a template of this file, see src/data/about.html in the KLatexFormula source code.

See also section Building a Translation Add-On below.

Translating the "What's New" dialog

The "What's New" dialog can be translated very much like the "About" dialog, by providing a file named whats-new-3.2_XX.html in the add-on directory data.

Translating the Command-Line Help Text

A translated command-line help text can be provided in the file cmdl-help_XX.txt, placed in the add-on directory data, like the texts for the "About" and "What's New" dialogs.

Building a Translation Add-On

Now you will want to create an Add-On with your translation. In short, make the following directory structure:

i18n/
  klf_XX.qm
data/
  about_XX.html
  cmdl-help_XX.txt
  whats-new-3.2_XX.html
info.xml
klf_XX.qrc

with klf_XX.qrc file containing:

<RCC>
  <qresource prefix="rccinfo">
    <file>info.xml</file>
  </qresource>
  <qresource>
    <file>i18n/klf_XX.qm</file>
    <file>data/about_XX.html</file>
    <file>data/cmdl-help_XX.txt</file>
    <file>data/whats-new-3.2_XX.html</file>
  </qresource>
</RCC>

and info.xml file containing:

<?xml version='1.0' encoding='UTF-8'?>
<rccinfo>
  <title>Ancient Greek Translation</title>
  <author>Your Name Here...</author>
  <description>Provides Ancient Greek user interface to KLatexFormula</description>
</rccinfo>

Of course, you should change XX and Ancient Greek to your locale and language. XX should be the 2-character code of your language (optionally followed by region, eg. fr_CH).

Now you can create the KLatexFormula Add-On, which is truly a Qt RCC file, with the command

rcc -binary -o i18n-klatexformula_XX.rcc klf_XX.qrc

The resulting file i18n-klatexformula_XX.rcc is an archive of all previously mentioned files, and that can be imported into klatexformula by dragging and dropping that file on the main window editor (as of 3.2.2). It can also be imported using KLatexFormula's Import Add-On option in the settings dialog. In other words, you can publish this file and any user can install it straightforward.