Translations

Slint’s translation infrastructure makes your application available in different languages.

Prerequisite

Install the slint-tr-extractor tool to extract translatable strings from .slint files:

cargo install slint-tr-extractor

bash

You can choose between runtime translations using gettext or bundling translations directly into your executable for platforms where gettext is unavailable or impractical.

To translate your application, follow these steps:

1. Identify all user-visible strings that need translation and annotate them with the @tr() macro.
2. Extract annotated strings by running the slint-tr-extractor tool to generate .pot files.
3. Use a third-party tool to translate the strings into .po files for each target language.
4. (For runtime gettext translations only) Convert .po files into .mo files using gettext’s msgfmt ↗.
5. (For bundled translations only) Configure bundling during the build process to embed translations into your application.
6. Use Slint’s API to select the appropriate translation based on the user’s locale.

At this point, all strings marked for translation will be automatically rendered in the selected language.

Annotating Translatable Strings

Use the @tr macro in .slint files to mark strings for translation. This macro supports formatting and pluralization, and can include contextual information.

The first argument must be a plain string literal, followed by the arguments:

Basic Example

export component Example {
    property <string> name;
    Text {
        text: @tr("Hello, {}", name);
    }
}

slint

Formatting

The @tr macro replaces each {} placeholder in the string marked for translation with the corresponding argument. It’s also possible to re-order the arguments using {0}, {1}, and so on. Translators can use ordered placeholders even if the original string did not.

You can include the literal characters { and } in a string by preceding them with the same character. For example, escaping the { character with {{ and the } character with }}.

Plurals

Use plural formatting when the translation of text involving a variable number of elements should change depending on whether there is a single element or multiple.

Given count and an expression that represents the count of something, form the plural with the | and % symbols like so:

@tr("I have {n} item" | "I have {n} items" % count).

Use {n} in the format string to access the expression after the %.

export component Example inherits Text {
    in property <int> score;
    in property <int> name;
    text: @tr("Hello {0}, you have one point" | "Hello {0}, you have {n} points" % score, name);
}

slint

Context

Disambiguate translations for strings with the same source text but different contextual meanings by adding a context to the @tr(...) macro using the "..." => syntax.

Use the context to provide additional context information to translators, ensuring accurate and contextually appropriate translations.

The context must be a plain string literal and it appears as msgctx in the .pot files. If not specified, the context defaults to the name of the surrounding component.

export component MenuItem {
    property <string> name : @tr("Default Name"); // Default: `MenuItem` will be the context.
    property <string> tooltip : @tr("ToolTip" => "ToolTip for {}", name); // Specified: The context will be `ToolTip`.
}

slint

Extracting Translatable Strings

Use slint-tr-extractor to generate a .pot file with all strings marked for translation:

find -name \*.slint | xargs slint-tr-extractor -o MY_PROJECT.pot

bash

This creates a file called MY_PROJECT.pot. Replace “MY_PROJECT” with your actual project name. To learn how the project name affects the lookup of translations, read the sections below.

Tip

.pot files are Gettext ↗ template files.

Translating Strings

Start a new translation by creating a .po file from a .pot file. Both file formats are identical. You can either copy the file manually or use a tool like Gettext’s msginit to start a new .po file.

The .po file contains the strings in a target language.

.po and .pot files are plain text files that you can edit with a text editor. We recommend using a dedicated translation tool for working with them, such as the following:

• poedit ↗
• OmegaT ↗
• Lokalize ↗
• Transifex ↗ (web interface)

Convert .po Files to .mo Files

Convert the human readable .po files into machine-friendly .mo files, which are a binary representation that is more efficient to read by code.

Use Gettext ↗’s msgfmt command line tool to convert .po files to .mo files:

msgfmt translation.po -o translation.mo

bash

For bundled translations, no conversion is needed; .po files are embedded directly.

Runtime Translations with Gettext

Slint can use the Gettext ↗ library to load translations at run-time.

Gettext expects translation files - called message catalogs - in following directory hierarchy:

• Directorydir_name/

  • Directorylocale/ e.g. fr, en, de, etc

    • DirectoryLC_MESSAGES/

      • domain_name.mo

• dir_name: the base directory that you can choose freely.

• locale: The name of the user’s locale for a given target language, such as fr for French, or de for German.

  The locale is typically determined using environment variables that your operating system sets.

• domain_name: Selected based on the programming language you’re using Slint with.

Tip

Read the Gettext documentation ↗ for more information.

Select and Load Translations

C++

First, enable the SLINT_FEATURE_GETTEXT cmake option when compiling Slint to gain access to the translations API and activate run-time translation support.

In C++ applications using cmake, the domain_name is the CMake target name.

Next, bind the text domain to a path using the standard gettext library.

To do so, add this in your CMakeLists.txt file:

find_package(Intl)
if(Intl_FOUND)
    target_compile_definitions(my_application PRIVATE HAVE_GETTEXT SRC_DIR="${CMAKE_CURRENT_SOURCE_DIR}")
    target_link_libraries(my_application PRIVATE Intl::Intl)
endif()

cmake

You can then setup the locale and the text domain

#ifdef HAVE_GETTEXT
#    include <locale>
#    include <libintl.h>
#endif

int main()
{
#ifdef HAVE_GETTEXT
    bindtextdomain("my_application", SRC_DIR "/lang/");
    std::locale::global(std::locale(""));
#endif
   //...
}

c++

For example, if you’re using the above and the user’s locale is fr, Slint looks for my_application.mo in the lang/fr/LC_MESSAGES/ directory.

Rust

First, enable the gettext feature of the slint crate in the features section to gain access to the translations API and activate run-time translation support.

Next, use the slint::init_translations! ↗ macro to specify the base location of your .mo files. This is the dir_name in the scheme of the previous section. Slint expects the .mo files to be in the corresponding sub-directories and their file name - domain_name - must match the package name in your Cargo.toml. This is often the same as the crate name.

For example:

slint::init_translations!(concat!(env!("CARGO_MANIFEST_DIR"), "/lang/"));

rust

For example, if your Cargo.toml contains the following lines and the user’s locale is fr:

[package]
name = "gallery"

toml

With these settings, Slint looks for gallery.mo in the lang/fr/LC_MESSAGES/gallery.mo.

Bundled Translations

Bundled translations embed the translated strings directly into your application binary. This approach is ideal for platforms like WASM or microcontrollers where gettext is unavailable.

Configure the Slint compiler to bundle translations by providing a path to the translations. Translation files should be organized in the following hierarchy:

path/<lang>/LC_MESSAGES/<domain>.po

plaintext

Bundling

C++

Set the SLINT_BUNDLE_TRANSLATIONS ↗ property in CMake:

set_property(TARGET my_application PROPERTY SLINT_BUNDLE_TRANSLATIONS "${CMAKE_CURRENT_SOURCE_DIR}/lang")

cmake

the <domain> is the cmake target name.

Rust

Use slint_build::CompilerConfiguration’s with_bundled_translations() ↗ function to set up bundling in build.rs:

let config = slint_build::CompilerConfiguration::new()
    .with_bundled_translations("path/to/translations");

rust

The <domain> is the crate name.

Selecting a Translation

If you enable the std feature with Slint, language for translations is detected based on the locale: if one of the bundled language matches the selected locale, it will be used.

C++

Use the slint::select_bundled_translation ↗ function to change translations at runtime.

Rust

Use the slint::select_bundled_translation ↗ function to change translations at runtime.

Previewing Translations with slint-viewer

Make sure the gettext feature was enabled when building slint-viewer. Use the --translation-domain and --translation-dir command line options to load translations for preview.