OpenParable
Skip to content
← Back to skills

Qt Translation Workflow

Development
qt-translation-workflow

Qt Translation Workflow is an Agent Skill for development published in the a5c-ai/babysitter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Set up Qt Linguist workflow with .ts files, lupdate/lrelease integration, and translation management

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/a5c-ai/babysitter/blob/HEAD/library/specializations/desktop-development/skills/qt-translation-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/qt-translation-workflow, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

qt-translation-workflow

Set up Qt Linguist translation workflow with .ts files and lrelease integration. This skill configures the complete internationalization pipeline for Qt applications.

Capabilities

  • Configure lupdate for string extraction
  • Set up .ts translation files
  • Integrate lrelease for .qm compilation
  • Generate CMake translation targets
  • Configure plural forms handling
  • Set up context-based translations
  • Generate translation status reports
  • Configure Qt Linguist project files

Input Schema

{
  "type": "object",
  "properties": {
    "projectPath": {
      "type": "string",
      "description": "Path to the Qt project"
    },
    "languages": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Target language codes (e.g., ['de', 'fr', 'ja'])"
    },
    "sourceLanguage": {
      "type": "string",
      "default": "en",
      "description": "Source language code"
    },
    "translationDir": {
      "type": "string",
      "default": "translations"
    },
    "includeQml": {
      "type": "boolean",
      "default": true
    },
    "pluralForms": {
      "type": "boolean",
      "default": true
    },
    "generateCMake": {
      "type": "boolean",
      "default": true
    }
  },
  "required": ["projectPath", "languages"]
}

Output Schema

{
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "language": { "type": "string" },
          "type": { "enum": ["ts", "qm", "cmake"] }
        }
      }
    },
    "commands": {
      "type": "object",
      "properties": {
        "extract": { "type": "string" },
        "compile": { "type": "string" }
      }
    }
  },
  "required": ["success"]
}

CMake Integration

# CMakeLists.txt

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

set(TS_FILES
    translations/myapp_de.ts
    translations/myapp_fr.ts
    translations/myapp_ja.ts
)

# Create translation targets
qt_add_translations(myapp
    TS_FILES ${TS_FILES}
    QM_FILES_OUTPUT_VARIABLE QM_FILES
    LUPDATE_OPTIONS -no-obsolete -locations relative
    LRELEASE_OPTIONS -compress
)

# Add to resources
qt_add_resources(myapp "translations"
    PREFIX "/translations"
    FILES ${QM_FILES}
)

Translation File Structure

project/
├── translations/
│   ├── myapp_de.ts
│   ├── myapp_fr.ts
│   ├── myapp_ja.ts
│   └── myapp_en.ts  # Reference
├── src/
│   ├── main.cpp
│   └── mainwindow.cpp
└── qml/
    └── main.qml

Source Code Setup

C++ Translations

// mainwindow.cpp
#include <QCoreApplication>

MainWindow::MainWindow() {
    // Simple translation
    setWindowTitle(tr("My Application"));

    // With context
    label->setText(QCoreApplication::translate("MainWindow", "Welcome"));

    // Plural forms
    QString message = tr("%n file(s) selected", "", count);

    // With disambiguation
    QString open1 = tr("Open", "menu item");
    QString open2 = tr("Open", "window title");

    // Dynamic translation
    QString format = tr("Hello, %1!");
    label->setText(format.arg(userName));
}

// Enable retranslation
void MainWindow::changeEvent(QEvent* event) {
    if (event->type() == QEvent::LanguageChange) {
        retranslateUi();
    }
    QMainWindow::changeEvent(event);
}

QML Translations

// main.qml
import QtQuick 2.15

Window {
    title: qsTr("My Application")

    Text {
        // Simple translation
        text: qsTr("Welcome to the app")
    }

    Text {
        // Plural forms
        text: qsTr("%n item(s)", "", itemCount)
    }

    Text {
        // With context
        text: qsTranslate("SettingsPage", "Language")
    }
}

Translation Loading

// main.cpp
#include <QTranslator>
#include <QLocale>

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    // Load system locale
    QTranslator translator;
    const QStringList uiLanguages = QLocale::system().uiLanguages();

    for (const QString &locale : uiLanguages) {
        const QString baseName = "myapp_" + QLocale(locale).name();
        if (translator.load(":/translations/" + baseName)) {
            app.installTranslator(&translator);
            break;
        }
    }

    // Or load specific language
    QTranslator germanTranslator;
    if (germanTranslator.load(":/translations/myapp_de")) {
        app.installTranslator(&germanTranslator);
    }

    return app.exec();
}

Language Switching

class LanguageManager : public QObject {
    Q_OBJECT
public:
    void setLanguage(const QString& languageCode) {
        // Remove old translator
        if (m_translator) {
            qApp->removeTranslator(m_translator);
        }

        // Load new translator
        m_translator = new QTranslator(this);
        QString path = QString(":/translations/myapp_%1").arg(languageCode);

        if (m_translator->load(path)) {
            qApp->installTranslator(m_translator);
            emit languageChanged();
        }
    }

signals:
    void languageChanged();

private:
    QTranslator* m_translator = nullptr;
};

Workflow Commands

# Extract strings from source
lupdate src/*.cpp qml/*.qml -ts translations/myapp_de.ts

# Extract with options
lupdate -recursive -locations relative -no-obsolete \
    src/ qml/ -ts translations/*.ts

# Compile translations
lrelease translations/*.ts

# Open in Qt Linguist
linguist translations/myapp_de.ts

Translation Status Report

# Check translation completeness
lconvert -if ts -i translations/myapp_de.ts -of csv -o status.csv

# Custom script to report status
for file in translations/*.ts; do
    total=$(grep -c '<source>' "$file")
    translated=$(grep -c 'type="finished"' "$file")
    echo "$file: $translated/$total translated"
done

Best Practices

  1. Use tr() everywhere: Mark all user-visible strings
  2. Provide context: Use disambiguation comments
  3. Handle plurals: Use %n with plural forms
  4. Use QString::arg(): For dynamic content
  5. Test RTL languages: Arabic, Hebrew support
  6. Keep translations updated: Run lupdate in CI

Related Skills

  • qt-cmake-project-generator - Project setup
  • desktop-i18n process - Full i18n workflow
  • docs-localization - Documentation localization

Related Agents

  • qt-cpp-specialist - Qt implementation
  • localization-coordinator - Translation management