Frameworks/Frameworks Localization Policy

Introduction

User visible text provided by frameworks should be translated and adapted to the user local settings. Most frameworks use the KI18n tier 1 framework to handle their translations. The only exception is other tier 1 frameworks, which cannot depend on KI18n. These frameworks use the Qt translation system.

Marking user visible text

Nothing unusual for KI18n-translated frameworks, they must use the KI18n API.

Qt-translated frameworks must use the Qt API (QObject::tr() and QCoreApplication::translate()), but with one subtlety regarding plural handling.

Qt handles plural forms differently from KI18n: for the English plural forms it expects the application to ship with a plural-only en.qm file. The KDE translation scripts can generate this file automatically, based on string metadata. Plural strings must be annotated with //~ singular <string> and //~ plural <string>.

Here is an example:

//~ singular %n day
//~ plural %n days
return tr("%n day(s)", 0, n);

Extracting user visible text

Frameworks use standard KDE Messages.sh files (TODO: techbase link) to extract user visible text into .po files.

Qt-translated framework subtleties

.po files are used for all frameworks, including those which use the Qt translation system. The only difference is that instead of calling $XGETTEXT, they must call $EXTRACT_TR_STRINGS. $EXTRACT_TR_STRINGS is the path to the [TODO extract-tr-strings] script, which uses lupdate and lconvert instead of xgettext. extract-tr-strings also takes care of generating a plural-only en.po file from the plural annotations.

To make sure the .po file is properly handled as a .po file which will be turned into a .qm file, its name should be suffixed with "_qt".

Loading translations

KI18n

For KI18n to load translations from the framework catalog, the preprocessor variable TRANSLATION_DOMAIN must be set to the catalog name. The simplest way to define this variable is to do so in the root CMakeLists.txt, like so:

add_definition(TRANSLATION_DOMAIN \"foo5\")

Qt

The classic way for a Qt-translated library to provide a translation is to install a .qm file and let the user code loads it, but this is error-prone. To avoid this, ECM can generate a source file which will load the .qm file at startup using Q_COREAPP_STARTUP_FUNCTION().

The ecm_create_qm_loader() function provides this feature. It accepts two arguments: a variable name where it stores the path to the generated source file and the catalog name. You use it like this:

ecm_create_qm_loader(bar_QM_LOADER bar5_qt)

set(bar_SRCS
    manager.cpp
    engine.cpp
    ...
    ${bar_QM_LOADER}
)

You can also reuse the existing source variable:

set(bar_SRCS
    manager.cpp
    engine.cpp
    ...
)

ecm_create_qm_loader(bar_SRCS bar)

Installing translations

Frameworks released archives are shipped with translations for all languages. This ensure a framework archive is self-contained, making it easier to use for a third-party developer. This is different from the way we used to work in the KDE4 days, where kdelibs translations were not in the kdelibs release archive.

Translated files are integrated at release time by the release managers: they are not stored in the framework git repository.

po directory hierarchy

Translated files are integrated in the release archive using this standard directory hierarchy:

    po/
        <lang>/
            *.po
            scripts/ # Used by KI18n for some languages which require special treatments
                <domain>
                    <domain>.js
            docs/
                *.docbook
                man-*.<section>.docbook
                kioslave5/
                    <name>/
                        *.docbook
                kcontrol5/
                    <name>/
                        *.docbook
                khelpcenter5/
                    <name>/
                        *.docbook

Depending on the framework some files may or may not be there. But if they are, they are organized using this hierarchy.

Installation code

Even if the translated files are not in the framework git repository. The code responsible for installing them must be there. To avoid errors while building from git (where the po directory does not exist), this code must first check whether the directory exists, like so:

if (IS_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/po")
    # Installation code goes here
endif()

Note: the IF uses the absolute path because according to CMake documentation IS_DIRECTORY only works when given absolute paths.

KI18n installation code

KI18n provides a ki18n_install() function. Similarly, KDocTools provides a kdoctools_install() function. These functions take one argument: the path to the po directory.

This is a typical example for a framework which uses KI18n and KDocTools:

if (IS_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/po")
    ki18n_install(po)
    kdoctools_install(po)
endif()

Qt installation code

ECM provides the ecm_install_po_files_as_qm() function to install the translated .po files. It works the same way ki18n_install()' works:

if (IS_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/po")
    ecm_install_po_files_as_qm(po) 
endif()