Building

To build Virtaal yourself, you will need a packaged archive of the Virtaal source code, or obtain it directly from Git.

To get the source code direction from Git use this command:

git clone git@github.com:translate/virtaal.git

Required Packages

The remaining Python packages above are all declared in pyproject.toml and installed automatically by pip install . - only GTK3/PyGObject/cairo and pycairo need installing separately first. pyproject.toml also has extras: spellcheck (pyenchant), test (see Testing) and docs (Sphinx).

Optional Packages

These are not build dependencies but usually improve the user experience.

  • Enchant, pyenchant (pip install .[spellcheck]) and GtkSpell3 – provides all spell checking functionality. The frozen Windows/macOS builds already bundle enchant + one starter dictionary each; only a from-source checkout needs these installed separately.

  • GNU gettext’s libgettextpo – for the msgfmt check; without it, that check is left out:

    • Linux: libgettextpo0 or similar

    • macOS: Homebrew’s gettext, already installed with gtk+3

    • Windows: gettextpo.dll, part of gvsbuild’s GTK3 build

  • iso-codes – if you want translated language names

  • glib-networking – uses the desktop’s proxy settings on Linux; usually installed with GTK

  • The optional fts3 module for sqlite3 will be used if it is available - provides speedups with TM retrieval (it is safe to just overwrite a better sqlite library over the one available in Python for Windows)

UNIX

You should be able to run Virtaal from the source tree. If you would like to install Virtaal:

pip install .

Distribution Packagers

For users running from a tarball, we do some dependency checking when starting Virtaal to be able to give accurate error messages in case of missing dependencies. However, if you have all of these sorted out in your package dependencies, there is no need for Virtaal to do this any more. In the file bin/virtaal, uncomment the line

#packaged = True

by removing the hash sign. This way Virtaal can start a bit quicker with no loss of functionality.

Linux (Flatpak)

Requires flatpak and flatpak-builder, plus the org.gnome.Platform/org.gnome.Sdk runtime at version 51:

flatpak remote-add --if-not-exists --user flathub \
  https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install --user flathub org.gnome.Platform//51 org.gnome.Sdk//51

cd devsupport/packaging/flatpak
flatpak-builder --user --install-deps-from=flathub --force-clean \
  --repo=repo build-dir io.github.translate.Virtaal.yml

This produces a local build in build-dir, runnable directly with:

flatpak-builder --run build-dir io.github.translate.Virtaal.yml virtaal

virtaal-python-deps.yaml is machine-generated from pyproject.toml via flatpak-builder-tools’ flatpak-pip-generator and shouldn’t be hand-edited except where noted in its own comments.

To make the single-file bundle CI attaches to each release:

flatpak build-bundle \
  --runtime-repo=https://dl.flathub.org/repo/flathub.flatpakrepo \
  repo Virtaal-linux-x86_64.flatpak io.github.translate.Virtaal

flatpak-builder builds for whatever CPU architecture it runs on - a real aarch64 CI runner and an aarch64 org.gnome.Platform runtime both already exist, so CI builds, smoke-tests and bundles both x86_64 and aarch64 as a matrix, rather than shipping only one.

Linux (AppImage)

The AppImage is a beta. It’s a PyInstaller bundle of Virtaal, Python, GTK and the spell checker, packed with appimagetool. Build it on Ubuntu 22.04: the AppImage runs on distributions with the same or a newer glibc. Install the packages listed at the top of devsupport/packaging/linux/build_appimage.sh, then:

xvfb-run -a devsupport/packaging/linux/build_appimage.sh

(xvfb-run only without a display: PyInstaller imports Virtaal’s modules, which start GTK.) This produces build/appimage/Virtaal-linux-<arch>.AppImage for the machine’s architecture.

The AppImage uses the host’s spelling dictionaries (/usr/share/hunspell) and the ones Virtaal downloads. When it starts, it adds its own menu entry and icon (virtaal-appimage in ~/.local/share), pointing at the AppImage file and without file associations. It leaves out the libraries every desktop already has: libxcb, the Wayland client libraries, fontconfig and freetype.

To check it in bare distribution images (needs Docker):

devsupport/packaging/linux/smoke_test_distro.sh fedora:44 \
  build/appimage/Virtaal-linux-x86_64.AppImage

Windows

Requires gvsbuild’s GTK3 build and Inno Setup, in addition to the running-from-source prerequisites above:

devsupport\packaging\windows\build_standalone.ps1
devsupport\packaging\windows\build_installer.ps1

The first produces a frozen dist\virtaal\ tree (PyInstaller, one-dir mode - see that script’s own comments for why not --onefile); the second wraps it into a single virtaal-<version>-setup.exe via Inno Setup (devsupport/packaging/windows/virtaal.iss).

macOS

A plain python3 -m venv can’t see Homebrew’s GTK3/PyGObject at all - create the venv with --system-site-packages instead, after installing the running-from-source prerequisites above via Homebrew (pygobject3 gtk+3 gtk-mac-integration, plus enchant gtkspell3 for spell checking):

brew install pygobject3 gtk+3 gtk-mac-integration enchant gtkspell3
python3 -m venv --system-site-packages .venv
. .venv/bin/activate
pip install .[test]
python bin/virtaal

Building a distributable .app/.dmg uses PyInstaller and dmgbuild on top of the above:

devsupport/packaging/macos/build_standalone.sh
devsupport/packaging/macos/codesign_app.sh
devsupport/packaging/macos/build_dmg.sh

The first produces dist/Virtaal.app (PyInstaller, settings in devsupport/packaging/macos/virtaal.spec), building in its own fresh build/standalone-venv rather than .venv, and fails if that venv can see packages Virtaal doesn’t depend on (PyInstaller may bundle them); the second signs it with the hardened runtime; the third wraps it into dist/Virtaal.dmg (settings in devsupport/packaging/macos/dmgbuild-settings.py). CI’s build-macos-app job runs these same scripts and uploads the results as workflow artifacts on every push.

codesign_app.sh signs ad-hoc unless CODESIGN_IDENTITY names a “Developer ID Application” certificate in your keychain, in which case build_dmg.sh signs the .dmg too. A Developer ID build can then be notarized and stapled with an App Store Connect API key:

APPLE_API_KEY_PATH=AuthKey_XXXXXXXXXX.p8 APPLE_API_KEY_ID=XXXXXXXXXX \
APPLE_API_ISSUER_ID=<issuer-uuid> \
  devsupport/packaging/macos/notarize.sh dist/Virtaal.dmg

CI does all of this when the repository has the MACOS_CERTIFICATE (base64 .p12), MACOS_CERTIFICATE_PWD, APPLE_API_KEY (base64 .p8), APPLE_API_KEY_ID and APPLE_API_ISSUER_ID secrets.

This produces a single-architecture build matching whatever Python/Homebrew it’s built with - Homebrew doesn’t ship universal2 GTK3 bottles, so there’s no lipo-style fat binary available here. An arm64-only build won’t run on an Intel Mac at all (Rosetta 2 only translates x86_64 -> arm64, never the reverse), so CI builds both architectures separately (a matrix job - see build-macos-app in ci.yml for the current runner labels; pull requests build arm64 only) and uploads them as separate artifacts (Virtaal-macos-app-arm64/-x86_64 and the .dmg equivalents) rather than one universal bundle.