Skip to content

Internationalization (i18n)

  • ✅ Auto translation generation: CMake build automatically generates .qm translation files
  • ✅ Multi-language support: built-in Chinese and English translations, extensible to any language
  • ✅ QTranslator integration: load translation files at runtime via QTranslator
  • ✅ Linguist editing: use Qt Linguist for visual translation editing

i18n Workflow

flowchart LR
    A[CMake build] --> B[Scan source → generate .ts]
    B --> C[Linguist edit translations]
    C --> D[Compile .ts → .qm]
    D --> E[Package into resources/qm files]
    E --> F[QTranslator load]

Translation File Generation

SARibbon's built-in dialogs and widgets require translation support for multilingual applications. When building with CMake, translation files are automatically generated in build-dir/src/SARibbonBar/i18n. In this directory you will find SARibbon_*.qm files, which are compiled translation files that can be loaded via QTranslator at application startup.

Loading Translation Files

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
int main(int argc, char* argv[])
{
    QApplication a(argc, argv);

    // Load SARibbon translation file
    QTranslator translator;
    if (translator.load("SARibbon_zh_CN.qm", ":/i18n/")) {
        a.installTranslator(&translator);
    }

    MainWindow w;
    w.show();
    return a.exec();
}

Adding New Translation Files

If you need to add a new language translation, follow these steps:

Open src/SARibbonBar/CMakeLists.txt and find the following section:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
##################################
# Translation
##################################
find_package(Qt${QT_VERSION_MAJOR}LinguistTools QUIET)
    if(Qt${QT_VERSION_MAJOR}LinguistTools_FOUND)
    # 2. Prepare the TS file list (supports multiple languages)
    set(TS_FILES
        i18n/SARibbon_zh_CN.ts
        i18n/SARibbon_en_US.ts
    )

    set(TS_SOURCES
        ${SARIBBON_HEADER_FILES}
        ${SARIBBON_SOURCE_FILES}
        ${SACOLOR_HEADER_FILES}
        ${SACOLOR_SOURCE_FILES}
    )
    # 3. Generate/update ts files + compile qm files
    # 4. Call the appropriate macro based on Qt version
    if(QT_VERSION_MAJOR EQUAL 5)
        qt5_create_translation(QM_FILES ${TS_SOURCES} ${TS_FILES})
    elseif(QT_VERSION_MAJOR EQUAL 6)
        qt6_create_translation(QM_FILES ${TS_SOURCES} ${TS_FILES})
    endif()
    # 5. Attach the generated qm files to the target
    target_sources(${SARIBBON_LIB_NAME} PRIVATE ${QM_FILES})

    message(STATUS "Translation support enabled (LinguistTools found).")
endif()

Add your translation file to TS_FILES, then run cmake to regenerate the project. Your ts file will be created in src/SARibbonBar/i18n.

Open the generated ts file with Qt Linguist, translate the strings, save, then rebuild. The corresponding qm file will be generated in build-dir/src/SARibbonBar/i18n.