GiellaLT provides rule-based language technology aimed at minority and indigenous languages
Below is a short description of what you need to install to be able to work with the keyboard build system. We assume that you have already installed the packages needed for general linguistic work.
sudo pip-3.5 install lxml PyICU PyYAML
If you have NOT installed the other packages (e.g. if you are only interested in keyboards), the following is the minimum you need on OSX (on other systems, install the same packages using the preferred package manager):
sudo port install autoconf automake libtool pkg-config \ imagemagick apache-ant python35 py35-pip sudo port select --set python3 python35 sudo pip-3.5 install lxml PyICU PyYAML
Also, it is a good idea to set up your signing environment.
All keyboard code is in github.com/giellalt, and each language has its own repository. Find the language you want to work with, and check it out using either git or svn.
NB! The whole keyboard infrastructure is changing at the moment, as the keyboard compiler tool (kbdgen) is being reworked to support a cleaner keyboard resource layout. There might be surprises.
There is an overview of the basic concepts on this page.
It is pretty simple:
xxx is the language code of the language you want.
xxx can also be
a longer name - it is possible to have multiple keyboards for the same project.
make command produces several output files:
doc/xxx_keyboards.svg- graphical overview of the layout
linux/xxx_keyboard.*- linux files (needs to be merged with the rest of the keyboard subsystem, should be done once when the keyboard design is settled
macos/xxx_keyboard.*- installation package (and source bundle) for macOS, ready to be installed
win/kbdxxxxx.klc- source file for MS Keyboard Layout Creator. Open the file in that app, and create an installer by selecting the menu Project > Build DDL and Setup Package
Things to consider/change:
pngfile will do)
.yamlextension) under the
layouts:key, separate with comma if you have several
copyrightetc to your likings
ISO-639-3code, consider adding the nearest
ISO-639-1code (even if it is a macro-language code), this will help in getting the keyboard(s) better integrated into the host OS as many of the OS’s don’t know a thing about
ISO-639-3languages. The broader language code should be used instead of the correct code for the attribute
locale:in the layout file. If you stick to the correct code, the end users will most likely only see the language code instead of a relevant language name.
The core component/tool for building keyboards is
kbdgen, a Python script
that converts the yaml keyboard descriptors into actual keyboard files. The
Github repo contains the source code, and
reference technical documentation is also
You can add a README file and a License file, as well as a background image for the installer package. Supported file formats are:
Valid filenames for the documentation are:
conclusion. All filenames can be capitalised.
To make the files be used by the package builder, add a
project.yaml file under
targets: like this:
targets: osx: packageId: no.uit.giella.keyboards.smj version: 0.1.0 bundleName: *bundleName icon: icon.png resources: doc
doc in the example above is the name of a directory containing
the files you want included in the installer. They will be picked up
automatically given they follow the naming conventions described above.
NB! When using
html as the file format, make sure you do not include
an xml header as the first line of text in the html file. That will cause the
file to be read as text, with all tags visible.
With recent changes to the keyboard generation tool
kbdgen, one can actually
build the final Windows installer in macOS or Linux. To do this, one has to run
the following setup sequence:
wine-2.10is known to work.
Add the bin dir of Wine to your
$PATH, and make sure that also
(a shell script) is available in the
$PATH. Close the terminal window
and open a new one before continuing.
Next, you need to install further tools, most easily done by running the following shell script (copy and paste into a suitable file, and make it executable):
#!/bin/sh export WINEARCH="win32" if [ -z "$WINEPREFIX" ]; then export WINEPREFIX="$HOME/.wine" fi INNO=http://www.jrsoftware.org/download.php/is-unicode.exe MSKLC=https://download.microsoft.com/download/1/1/8/118aedd2-152c-453f-bac9-5dd8fb310870/MSKLC.exe echo "Getting Inno Setup…" curl -OL "$INNO" echo "Getting MSKLC…" curl -O "$MSKLC" echo "Installing dotnet20 with winetricks…" winetricks -q dotnet20 echo "Installing MSKLC…" unzip -o `basename $MSKLC` msiexec /i MSKLC.msi /passive echo "Installing Inno Setup…" wine `basename $INNO` /SILENT echo "Done!" echo echo "You will want to put the following in your .profile or a script you source before running kbdgen:" echo echo "export WINEARCH=\"win32\"" echo "export WINEPREFIX=\"$WINEPREFIX\"" echo "export INNO_PATH=\"\$WINEPREFIX/drive_c/Program Files/Inno Setup 5\"" echo "export MSKLC_PATH=\"\$WINEPREFIX/drive_c/Program Files/Microsoft Keyboard Layout Creator 1.4\""
After having saved the script and made it executable, run it, and follow the instructions printed at the end of how to install the remaining dependencies.
Finally, you need to add a real
uuid for each language. Run the command:
and paste the generated
uuid in the
project.yaml file under
targets: win: uuid:. Now you are ready to run
make win, and get a working installer. If no installer is built, uncomment
RELEASE variable in
In some cases, especially the Sámi languages, one has to add a locale specification for Windows containing the Script system being used. That is, for each layout file, you also need to add something like the following:
targets: win: locale: sma-Latn-NO
Repeat for all layout files. If not added, the keyboard won’t integrate properly with Windows. Identifying which languages will need such a specification is a feature that will be added in the near future.
Desktop keyboards are relatively complex things, and to get a head start, and at the same time ensure that one is as close as possible to the majority language keyboard that the users are accustomed to, one should create a draft keyboard layout based on data from CLDR. The command is:
make draft XML_SRC=xx
xx is either a two-letter language code, or the full filename +
platform string in the format
platform/filename. If you don’t know what
to put there, just leave out the
xx, and you will be given a list of all
the alternatives. The two-letter language code will give you a macOS-based draft
keyboard layout. If you want to draft for another platform, you need the full
See the note above on the use of language codes for best compatibility with Windows and macOS.
The generated keyboard (using the linked MS Keyboard Layout Creator (see above)
can only be guaranteed to work with Windows 7 and newer. This is especially true
for languages with language codes only in
ISO 639-3. The keyboard is
compatible with Windows 10.
The keyboard package is compatible with most versions of macOS, going back all the way to macOS version 10.2 (Jaguar).
The generated code is directly compatible with existing code, but must be merged with it. One should develop the keyboard using the other OS’s, and only when one is done with the keyboard layout should one submit the code for inclusion in the Linux keyboard driver code.
The mobile keyboards have more dependencies, documentation is linked below. They also differ from desktop keyboards in that the keyboards are full-blown apps, and you need all the machinery to build and distribute apps through the relevant stores. The desktop keyboards are less appy, mostly just plain text files (with Windows keyboards as an exception).
This is not enough, more instructions to come.
This is not enough, more instructions to come.
Run the commands:
export GIELLA_TEMPLATES=/path/to/giella-templates cd $GTHOME/keyboards ./autogen.sh ./configure make NEW_LANGS=xxx
xxx with the actual language code of the language you want to add.
If you want to add multiple languages, enclose the list within double quotes.
When the new language dir is populated with Makefile’s and template data, commit
the whole dir to svn. Remember to also commit the files
When done, start editing the
$NEW_LANGS.yaml file, and run
make. Have a
look at the layout of the keyboard by opening
doc/layout.html in a web