Univention Corporate Server - Manual for developers

Download PDF

Translating a single Debian package

12.1. Translating a single Debian package#

When creating a new package or updating an existing one, it is possible to provide a translation for that package by following the workflow described in this section. Examples in this section use the German translation, but they are applicable to any other language as well.

12.1.1. Setup of univention-l10n-build#

The setup depends on the operating system developers use to develop the package. A running UCS installation is recommended, where translators can set up the tools with univention-install, see Setup on a UCS machine. Otherwise, follow the instructions in section Setup on a non-UCS machine. Both setup variants provide the command univention-l10n-build.

12.1.1.1. Setup on a UCS machine#

Install the package univention-l10n-dev as root:

$ univention-install univention-l10n-dev

After the installation of univention-l10n-dev, the command univention-l10n-build is available for the following steps.

Skip the next section and continue with UCS package translation workflow.

12.1.1.2. Setup on a non-UCS machine#

First, install Git, Python 3.7 or later and pip. For example, run the following command on Ubuntu 20.04:

$ sudo apt-get install git python3 python3-pip

To checkout the latest version of the UCS Git repository, if not yet available, use the following commands:

$ mkdir ~/translation
$ cd ~/translation
$ git clone \
   --single-branch --depth 1 --shallow-submodules \
   https://github.com/univention/univention-corporate-server

Install the python package univention-l10n with pip:

$ pip install ~/translation/univention-corporate-server/packaging/univention-l10n/

Pip installs all required Python packages and the command univention-l10n-build.

12.1.2. UCS package translation workflow#

The translation process is divided into the following steps:

  1. Prepare the source code for translation.

  2. Add and/or update supplementary files.

  3. Run univention-l10n-build for the package.

  4. Translate the strings by editing the .po files.

The .po files used in this section contain the German language code de in the file de.po. Use the appropriate language code from the ISO-639-1 list for other languages.

12.1.2.1. Prepare the source code#

Mark all strings that need translation within the source code. See the following example for a Python file:

from univention.lib.i18n import Translation
_ = Translation("<packagename>").translate
example_string = _("Hello World!")

Replace <packagename> with the wanted gettext domain, for example the name of the UCS Debian package like the existing package univention-management-console-module-udm.

For UMC XML files, the translatable XML elements are automatically added to their associated de.po file. This includes XML elements like name, description, keywords, and more.

For UMC JavaScript module files, include the translation function _ in the define function:

define([
    "umc/i18n!umc/modules/<module>"
], function(_) {
    var example_string = _("Hello World");
})

Replace <module> with the module id (examples for existing packages: appcenter, udm).

12.1.2.2. Add and/or update supplementary files#

The program univention-l10n-build needs to know which source files target which de.po file. de.po files associate translatable strings with their translations and are meant to be edited manually. For more information, see the gettext framework upon which univention-l10n-build is based.

For a UMC package, de.po files are automatically created for its associated XML file, the JavaScript files and the Python module, see debian/package.umc-modules about UMC modules.

Other source files have to be declared with .univention-l10n files that are located in the debian directory and structured like the following example from the package univention-appcenter:

[
        {
                "input_files": [
                        "udm/.*"
                ],
                "po_subdir": "udm/handlers/appcenter",
                "target_type": "mo",
                "destination": "usr/share/locale/{lang}/LC_MESSAGES/univention-admin-handlers-appcenter.mo"
        }
]

This file instructs univention-l10n to compile a de.po file in the directory udm/handlers/appcenter which includes translations for all files below the directory udm. The name univention-admin-handlers-appcenter has to be replaced with the wanted gettext domain, for example the name of the new or updated Debian package. Additionally, if there are one or more .univention-l10n files, add univention-l10n to the add-on list in the debian/rules file:

$ dh --with univention-l10n

As an example, refer to the following file tree of the appcenter package, which displays all relevant files for the translation inside the package:

├── debian
│    ├── rules
│    ├── univention-management-console-module-appcenter.umc-modules
│    ├── univention-management-console-module-appcenter.univention-l10n
│    └── ...
├── ...
├── udm
│   └── handlers
│       └── appcenter
│           ├── de.po
│           └── ...
└── umc
    ├── appcenter.xml
    ├── de.po
    ├── ...
    ├── js
    │   ├── de.po
    │   ├── appcenter.js
    │   └── ...
    └── python
        └── appcenter
            ├── de.po
            ├── __init__.py
            └── ...
debian/rules

Add univention-l10n add-on if non-UMC files have to be translated.

debian/univention-management-console-module-appcenter.umc-modules

See debian/package.umc-modules.

debian/univention-management-console-module-appcenter.univention-l10

Instructions for translatable non-UMC files.

udm/handlers/appcenter/de.po

Only created/updated if defined in univention-management-console-module-appcenter.univention-l10n.

umc/appcenter.xml

UMC standard XML file.

umc/de.po

UMC standard de.po file for appcenter.xml.

umc/js/de.po

UMC standard de.po file for all JavaScript files.

umc/js/appcenter.js

One of the JavaScript files with translatable strings.

umc/python/appcenter/de.po

UMC standard de.po file for all Python files.

umc/python/appcenter/__init__.py

One of the Python files with translatable strings.

12.1.2.3. Run univention-l10n-build#

Run the command univention-l10n-build in the package directory. The program finds all marked strings and either updates or creates the corresponding de.po file.

Warning

univention-l10n-build updates every package in the current working directory and below. Make sure to run the program from inside the package directory, if this is not the desired outcome.

12.1.2.4. Translate#

After univention-l10n-build finished, the translation can start. Edit the de.po files with a text editor. Find all empty msgstr fields and enter the translation of the corresponding msgid. See Editing translation files for details.

After the translation step, build and test the package on a UCS installation. Repeat this workflow every time a marked string is changed or a new one is added to the source files.

On this page