wittrans

A command-line tool and a Python library to search for translated strings and source messages in .mo localization files used by Linux distributions.

• wittrans
  • Overview
  • Key Features
  • Screenshots
  • Installation
    • Prerequisites
    • Install via uv
    • Install via pipx
  • Using Command Line Interface
    • Search
    • Export
    • Parameters
    • Options
    • Examples
  • Using API
    • Search
    • Get All Results
  • Documentation
    • Online Documentation
    • Search Paths
    • TSV Output Format
    • Notes
    • External Links
  • Contributing
    • Reporting Issues
  • License

Overview

wittrans is a command-line utility designed to search through compiled .mo localization files in Linux distributions. Finding and verifying translations in Linux systems can be tedious, especially when dealing with inconsistent translations, spelling errors, or locating the source of a specific translation. The main use case is to simplify this process by enabling fast, comprehensive searches across installed .mo files in a specified language.

The project name comes from the common question: "Where is that translation?"

Key Features

• ✨ Fast search through compiled .mo files in system-wide programs and Flatpak apps
• 🔍 Case-insensitive search functionality
• 📝 Search capability in both English source text and translations
• 🌍 Support for all system-available language codes
• 📊 Search results can be displayed in the console or exported to a TSV file
• 🧩 First-class command-line utility, and provides an experimental public API
• 🐛 Find spelling mistakes easily!

Screenshots

Show

wittrans help output

wittrans searching for term "maanantai" in Finnish

Installation

wittrans is available on PyPI and can be installed using a Python package manager, such as uv, pipx, or pip. The only requirement is that wittrans must be run on a GNU/Linux distribution for proper path resolution.

Prerequisites

• GNU/Linux distribution
• Python >= 3.13 (runtime)
• uv >= 0.8.11, pipx >= 1.7.1, or pip >= 24.3.1 (for installation)

Install via uv

Install wittrans as a standalone command-line tool using uv:

uv tool install wittrans

Install via pipx

Install wittrans as a standalone command-line tool using pipx:

pipx install wittrans

Using Command Line Interface

Search

After installation, use wittrans as a command:

wittrans "search_term" language_code

Export

Export search results to a TSV file using -o:

wittrans "search_term" language_code -o tsv

Export all strings from language-specific translation (.mo) files:

wittrans language_code -a -o tsv

Parameters

Parameter	Description	Example
search_term	Text to search for (in quotes)	"maanantai"
language_code	Two-letter ISO-639 Set-1 language code, or three-letter ISO-639 Set-2 or Set-3 language code, or locale code as in GNU C Library	fi, fin, fi_FI for Finnish

Options

Option	Description	Example
-i, --indicate	Highlight search term matches in output	-i
-f, --no-flatpak	Skip searching Flatpak applications (faster search)	-f
-s, --source	Search only in source strings (cannot be used with -t)	-s
-t, --translation	Search only in translation strings (cannot be used with -s)	-t
-w, --whole-word	Match whole words only instead of partial matches	-w
-o, --output	Output format. Supports tsv for tab-separated values	-o tsv
--output-file	Custom output filename (used with -o option). If not specified, auto-generated filename is used	--output-file my_results.tsv
-a, --all	Retrieve all translations from .mo files (cannot be used with search term, requires -o tsv for output)	-a -o tsv
--version	Show version number and exit	--version
-h, --help	Show help message and exit	-h

Examples

Find "maanantai" (Monday) in Finnish translations:

wittrans "maanantai" fi

Find "måndag" (Monday) in Swedish translations with result highlighting:

wittrans "måndag" sv -i

Find "lunes" (Monday) in Spanish translations, skipping Flatpak for faster search:

wittrans "lunes" es -f

Find "segunda-feira" (Monday) in Brazilian Portuguese translations and export to a TSV file:

wittrans "segunda-feira" pt_BR -o tsv

Find "星期一" (Monday) in Chinese translations and export to a TSV file with a custom name:

wittrans "星期一" zh_CN -o tsv --output-file chinese_monday.tsv

Using API

Starting with version 0.8.0, the public API has two public functions. Do note that wittrans is mainly intended to be used as a CLI tool, and the public API is experimental. For pure API usage, there still exists a dependency on "rich" library - this is not ideal when importing as a library. The public API SHOULD NOT be considered stable. For API reference, see the online documentation.

Import wittrans:

from wittrans import get_translations, search

Search

Search for a term across all installed translation files in .mo format for a given language. For more documentation, please see docs directory.

results = search("maanantai", "fi")

Get All Results

Retrieve all translation strings from installed .mo files for a given language. For more documentation, please see docs directory.

all_results = get_translations("fi")

Documentation

Online Documentation

For the latest documentation, there is an online version available at https://wittrans.readthedocs.io/en/latest/.

Search Paths

To locate .mo translation files, the following 14 standard paths are used, covering system-wide and user-specific directories:

Path	Description
/usr/share/locale/{lang_code}/LC_MESSAGES	Primary system-wide translations directory. Contains the original .mo files installed by application packages through the system's package manager.
/usr/share/locale-langpack/{lang_code}/LC_MESSAGES	Supplementary system-wide translations directory used by Ubuntu and some derivatives. Contains additional translations that can be installed separately via language packs.
/usr/local/share/locale/{lang_code}/LC_MESSAGES	System-wide translations for manually installed software. Contains translations for applications installed by administrators outside the package manager (e.g., compiled from source).
~/.local/share/locale/{lang_code}/LC_MESSAGES	User-specific translations directory. Contains translations for applications compiled and installed by the current user in their home directory.
/var/lib/flatpak/app	System-wide Flatpak application translations, accessible to all users. Each Flatpak app maintains its own locale directory within its sandbox. All installed architectures (e.g. x86_64, aarch64) and branches (e.g. stable, master, beta) are searched, typically under {app_id}/{arch}/{branch}/active/files/share/locale/{lang_code}/LC_MESSAGES or {app_id}/{arch}/{branch}/active/files/locale/{lang_code}/LC_MESSAGES.
/var/lib/flatpak/runtime	System-wide Flatpak runtime translations, accessible to all users. All installed architectures and branches are searched, with runtime locale files typically found under {runtime_id}.Locale/{arch}/{branch}/active/files/{lang_code}/share/{lang_code}/LC_MESSAGES.
~/.local/share/flatpak/app	User-specific Flatpak application translations, only accessible to the current user. Follows the same directory structure as system-wide Flatpak applications. Supports all architectures and branches.
~/.local/share/flatpak/runtime	User-specific Flatpak runtime translations, only accessible to the current user. Follows the same directory structure as system-wide Flatpak runtimes. Supports all architectures and branches.
/usr/share/gnome-shell/extensions/{extension_name}/locale/{lang_code}/LC_MESSAGES	System-wide GNOME Shell extensions. Contains translations for extensions installed system-wide by the package manager or administrator.
/usr/local/share/gnome-shell/extensions/{extension_name}/locale/{lang_code}/LC_MESSAGES	User-specific GNOME Shell extensions in system location. Extensions manually installed to the system-wide location by users with appropriate permissions.
~/.local/share/gnome-shell/extensions/{extension_name}/locale/{lang_code}/LC_MESSAGES	User-specific GNOME Shell extensions. Contains translations for extensions installed by current user through GNOME Extensions website or manual installation.
/usr/share/plasma/plasmoids/{plasmoid_name}/contents/locale/{lang_code}/LC_MESSAGES	System-wide KDE Plasmoids (widgets). Contains translations for KDE widgets and plasmoids installed to all users.
/usr/local/share/plasma/plasmoids/{plasmoid_name}/contents/locale/{lang_code}/LC_MESSAGES	System-wide KDE Plasmoids (widgets). Contains translations for KDE widgets installed to all users by an administrator outside the package manager.
~/.local/share/plasma/plasmoids/{plasmoid_name}/contents/locale/{lang_code}/LC_MESSAGES	User-specific KDE Plasmoids (widgets). Contains translations for KDE widgets installed by current user.

TSV Output Format

When using -o tsv, the output file contains the following tab-separated columns:

Column	Description
Source Type	Source category of translation, e.g. "System Locale or "System Flatpak". There are eight different categories
File Path	Full path to the translation file
Context	Translation context (if available)
Original Text	English source text
[Language] Translation	Translated text in the specified language

TSV files can be opened in spreadsheet applications (LibreOffice Calc, etc.).

Notes

• Results include matches in both source text and translations
• .mo files are the compiled binary versions of .po files used by the system
• ISO-639 Set-1 language codes are the primary, supported way for setting language code
• While there is a preliminary support for ISO-639 Set-3 codes and locale codes, such as zh_CN and pt_BR, provided by GNU C Library, all the system-available locale codes have not been tested and might not work as reliably as Set-1 codes. Run locale -a in command line to see available locales.

External Links

• GNU gettext
• The Format of GNU MO Files
• GNU C Library locales
• ISO 639 Code Tables
• Filesystem Hierarchy Standard

Contributing

Code contributions of all kinds are welcome: bug fixes, new features, and more. See CONTRIBUTING.md for development setup, code guidelines, and how to submit changes.

Reporting Issues

Report issues to Codeberg issue tracking system.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the LICENSE file for details.