spiegel-keyman/docs/linux/keyman-config.md

Linux km-config

Code for km-config is in linux/keyman-config.

Preparing to run

Install Dependencies

If you are running from the repo or installing keyman-config manually rather than from a package then you will need to:

sudo apt install python3-lxml python3-magic python3-numpy python3-qrcode python3-pil \
    python3-requests python3-requests-cache python3 python3-gi gir1.2-webkit2-4.1 dconf-cli \
    python3-setuptools python3-pip python3-dbus ibus libglib2.0-bin liblocale-gettext-perl \
    python3-build python3-fonttools python3-sentry-sdk

Newer Ubuntu versions (>= 24.04) don't allow to modify the environment and directly install non-Debian-packaged Python packages. Instead you'll have to run the commands in a virtual environment.

This requires the installation of some additional dependencies:

sudo apt install python3-venv libglib2.0-dev libdbus-1-dev pkg-config
libcairo2-dev libgirepository-2.0-dev

Then create the virtual environment with python3 -m venv km-venv and activate it with source km-venv/bin/activate.

Prepare code

Run linux/keyman-config/build.sh build to prepare the code.

Installation

You can install the files with linux/keyman-config/build.sh install. This will install the files into /usr/local.

To uninstall you can run linux/keyman-config/build.sh uninstall.

Manually installing

If you prefer to manually copy the files you'll still have to run the build step above. In addition you'll have to copy the GSettings schema:

GSettings schema

Copy and compile the GSettings schema:

sudo cp linux/keyman-config/resources/com.keyman.gschema.xml /usr/share/glib-2.0/schemas
sudo glib-compile-schemas /usr/share/glib-2.0/schemas

Standards data file

Running km-config requires a language tag mapping file keyman_config/standards/lang_tags_map.py. This file gets generated during a package build, and also when running build.sh build.

Things to run from the command line

km-config

./km-config

This displays a configuration panel that shows the currently installed Keyman keyboard packages and can download and install additional keyboards.

Buttons

• Uninstall - uninstall selected keyboard
• About - show information about selected keyboard
• Help - display help documentation about selected keyboard
• Options - display options.htm form for setting keyboard options

---

• Refresh - useful if you install or uninstall on the commandline while running km-config.
• Download - runs DownloadKmpWindow (see below)
• Install - opens a file choose dialog to choose a kmp file to install and bring up the InstallKmpWindow for more details and to confirm installing.
• Close - close the configuration panel

Download window

This uses the keyman.com website to install kmps.

Search for a language or keyboard in the search box. Select a keyboard from the list. In 'Downloads for your device' there will be an 'Install keyboard' button for the keyboard for Linux. Click it to download the keyboard and bring up the InstallKmpWindow for more details and to confirm installing.

Secondary-click gives you a menu including 'Back' to go back a page.

km-package-install

km-package-install -p <keyboard package id> install Keyman keyboard package from the keyman.com server

km-package-install -f <kmp file> install Keyman keyboard package from a local .kmp file

km-package-uninstall

km-package-uninstall <keyboard id> uninstall Keyman keyboard package

km-package-uninstall -s <keyboard id> uninstall from shared area /usr/local

km-package-list-installed

km-package-list-installed shows name, version, id, description of each installed keyboard

km-package-list-installed -s shows those installed in shared areas

km-package-list-installed -os shows those installed by the OS

km-package-list-installed -u shows those installed in user areas

km-package-get

km-package-get <keyboard id> download Keyman keyboard package to ~/.cache/keyman

km-kvk2ldml

km-kvk2ldml [-p] [-k] [-o LDMLFILE] <kvk file> Convert a Keyman kvk on-screen keyboard file to an LDML file. Optionally print the details of the kvk file (-p) optionally with all keys (-k).

This command is run automatically when installing a keyboard package to create the necessary files for the onboard onscreen keyboard.

Building the Debian package

See the packaging.md document.

Internationalization

Create or update i18n template file

Run

make update-template

This will create or update the file locale/keyman-config.pot.

Add translations for a new language

To add translations for a new language run (replacing de_DE with the desired locale):

cd locale
msginit --locale=de_DE.UTF-8 --width=98 --input keyman-config.pot

This will create the file locale/de.po.

NOTE: Specifying UTF-8 is important if any non-ASCII characters will be used in the translation, i.e. always.

NOTE: This step is not necessary when using Crowdin

Update translations

After strings were added or modified the translated po files need to be updated. For this call, replacing de with the desired locale:

make locale/de.po

Alternatively you can also update all po files at once:

make update-po

NOTE: This step is not necessary when using Crowdin

Compile translations

To create the binary files for the translations, run:

make compile-po

This will create .mo files, e.g. locale/de/LC_MESSAGES/keyman-config.mo.

Testing localization

TEXTDOMAINDIR=./locale LANGUAGE=de ./km-config

Testing that all strings are localizable

To test that all strings can be translated, you can run the following command. This will create and compile a TEST.po file which shows all localizable strings in uppercase, and then run km-config with the TEST.po file.

make test-po

Debugging unit tests

• Add the following lines to your workspace settings file (.vscode/settings), or copy docs/settings/linux/settings to .vscode/settings)

  "python.envFile": "${workspaceFolder}/linux/keyman-config/tests/python.env",
  "python.testing.unittestArgs": [
    "-v",
    "-s", "linux/keyman-config/tests",
    "-p", "*_tests.py"
  ],
  "python.testing.unittestEnabled": true,
  

• The tests will show up in the Test Explorer in VSCode and can be debugged there