En esta página

Ejemplo de reloj con hora local

El ejemplo muestra las mejores prácticas para utilizar las funciones de traducción y localización de Qt en CMake y Qt Quick, incluyendo el tratamiento de los plurales en diferentes idiomas y los formatos de fecha y hora localizados.

Consulta el Manual deQt Linguist para obtener más información sobre la traducción de aplicaciones Qt.

Interfaz de usuario

El ejemplo muestra la hora y la fecha actuales en la configuración regional y el idioma de tu sistema. Además, los textos de la interfaz de usuario están traducidos a los siguientes idiomas: inglés, alemán, francés, español, italiano, japonés, coreano, portugués, árabe y chino. Si tu escritorio está en otro idioma, se utilizará el inglés por defecto.

Para probar diferentes idiomas y configuraciones regionales sin modificar el sistema, el ejemplo también admite una configuración regional como argumento de la línea de comandos. Por ejemplo, al iniciar localizedClock desde la línea de comandos con la opción « --locale de », el reloj se muestra en alemán, con el formato de fecha y hora habitual en Alemania.

La captura de pantalla muestra la versión en_US:

Captura de pantalla de un reloj digital en inglés (EE. UU.)

Internacionalización

En la aplicación, la traducción se utiliza para establecer el título de la ventana principal y algunos textos de la interfaz de usuario, incluidos aquellos con marcadores de posición y formas plurales. La aplicación cuenta los segundos con las formas plurales activadas (véase «Gestión de formas plurales»). Como resultado, dependiendo del número de segundos, la función de traducción devuelve una traducción diferente, con el número gramatical correcto para el idioma de destino. Por ejemplo, en inglés, si el número es mayor que uno, se utiliza la forma plural; en caso contrario, se utiliza la forma singular. En «Reglas de traducción para formas plurales» encontrarás las reglas de plural para diferentes idiomas.

La configuración regional también influye en cómo se muestran las fechas y las horas. Estas se formatean según las convenciones del país de la configuración regional actual. Por ejemplo, una configuración regional alemana muestra la hora en formato de 24 horas y el día escrito antes del mes, mientras que una configuración regional de EE. UU. utiliza el formato de 12 horas y el mes se escribe antes del día.

Esta captura de pantalla muestra la versión en_GB. Obsérvese que el formato de las fechas es diferente al de la versión en_US anterior, aunque en ambos casos se ha cargado la misma traducción al inglés en plural.

Captura de pantalla de un reloj digital en inglés (Reino Unido)

Aquí tienes la captura de pantalla de la versión de_DE, que, al igual que la de GB, tiene un formato de fecha distinto al de EE. UU. Fíjate en que la traducción al alemán para las formas regulares y plurales se carga en consecuencia.

Captura de pantalla de un reloj digital en alemán

Implementación

La implementación consta de tres partes:

CMakeLists.txt

El archivo CMake de la aplicación habilita la compatibilidad con la traducción y la localización de Qt. A continuación se muestran los fragmentos relevantes:

find_package(Qt6 REQUIRED COMPONENTS Core Linguist Qml Quick): Busca y vincula los módulos necesarios de Qt 6, incluidos Linguist, que son esenciales para la internacionalización.

qt_standard_project_setup(...): Configura el sistema de internacionalización con soporte para las configuraciones regionales indicadas. I18N_SOURCE_LANGUAGE se deja en su valor por defecto (inglés), ya que el código fuente contiene textos en inglés.

qt_standard_project_setup(REQUIRES 6.8
    I18N_TRANSLATED_LANGUAGES de ar ko zh ja fr it es pt)

qt_add_translations(...): Agrupa la funcionalidad de lupdate y lrelease generando los archivos fuente de traducción (archivos TS) en el directorio «i18n» utilizando clock como nombre base, y compilándolos en archivos binarios .qm si contienen traducciones. Se generan los siguientes archivos TS:

  • «clock_{de, ar, ko, zh, ja, fr, it, es, pt}.ts»: un archivo TS por cada idioma que aparece en I18N_TRANSLATED_LANGUAGES de qt_standard_project_setup, que contiene las traducciones a ese idioma.
  • «clock_en.ts»: contiene las formas plurales en inglés, ya que el código fuente incluye una traducción en plural («%n second(s)»). La función qt_add_translations escribe aquí únicamente las formas plurales, ya que hemos especificado el idioma de los textos en el código fuente como inglés, dejando I18N_SOURCE_LANGUAGE con el valor por defecto. Por lo tanto, los textos normales no necesitan traducción.
qt_add_translations(localizedClock
    TS_FILE_BASE i18n/clock
    RESOURCE_PREFIX i18n
)

qt_add_qml_module(...): Añade un módulo QML bajo el URI qtexamples.localizedclock, que incluye el archivo Main.qml.

qt_add_qml_module(localizedClock
    URI qtexamples.localizedclock
    VERSION 1.0
    QML_FILES
        Main.qml
)
main.cpp

El punto de partida de la aplicación. Esta parte se encarga de configurar la configuración regional, instalar las traducciones necesarias y cargar la interfaz de usuario. A continuación se explica el código relevante:

Define el argumento de configuración regional, por ejemplo, --locale en_US o --locale de_DE:

    QCommandLineParser parser;
    QCommandLineOption localeOption("locale"_L1, "Locale to be used in the user interface"_L1,
                                    "locale"_L1);
    parser.addOption(localeOption);
    parser.addHelpOption();
    parser.process(app);

Analizar los argumentos, obtener la configuración regional proporcionada y establecer la configuración regional de entrada como la configuración regional predeterminada de la aplicación:

        QLocale locale(parser.value(localeOption));
        qInfo() << "Setting locale to" << locale.name();
        QLocale::setDefault(locale);

Instala la traducción al inglés independientemente de la configuración regional, para permitir traducciones incompletas en otros idiomas. QTranslator consulta las traducciones de los textos en el orden inverso al que están instaladas:

    QTranslator enPlurals;
    const auto enPluralsPath = ":/i18n/clock_en.qm"_L1;
    if (!enPlurals.load(enPluralsPath))
        qFatal("Could not load %s!", qUtf8Printable(enPluralsPath));
    app.installTranslator(&enPlurals);

Instala una traducción según la configuración regional especificada. Como la traducción al inglés ya se ha instalado en el paso anterior, es posible que acabemos teniendo dos traducciones instaladas. Qt utiliza la traducción instalada más recientemente para cualquier clave que se solape. Por lo tanto, la traducción específica de la configuración regional tendrá prioridad sobre la del inglés y, en caso de que falte alguna traducción, QTranslator recurrirá al inglés.

    QTranslator traducción;
    if (QLocale().language() != QLocale::English) {
        if (traducción.load(QLocale(), "clock"_L1, "_"_L1, ":/i18n/"_L1)) {
            qInfo("Loading translation %s",
                  qUtf8Printable(QDir::toNativeSeparators(translation.filePath())));
            if (!app.installTranslator(&translation))
                qWarning("Could not install %s!",
                         qUtf8Printable(QDir::toNativeSeparators(translation.filePath())));
        } else {
            qInfo("Could not load translation to %s. Using English.",
                  qUtf8Printable(QLocale().name()));
        }
    }
Main.qml

Este archivo QML define la ventana principal de la interfaz de usuario de la aplicación, que muestra la hora, la fecha, la configuración regional utilizada y un contador de segundos. A continuación se explica el código relevante:

Establece el título de la ventana utilizando qsTr() para la traducción. Para encontrar la traducción de este texto, QTranslator consulta en el archivo TS del idioma actual el texto «Digital Clock» dentro del contexto «Main» (el nombre del archivo):

title: qsTr("Digital Clock")

Muestra el número de segundos utilizando qsTr() con soporte para el plural (numeral). La forma plural se habilita utilizando la notación especial «%n» (véase «Gestionar formas plurales»). Dependiendo del valor de n, la función de traducción devuelve una traducción diferente, con el número gramatical correcto para el idioma de destino. Por ejemplo, en inglés, si el valor de root.seconds es mayor que uno, se utiliza la forma plural; de lo contrario, se utiliza la forma singular. En «Reglas de traducción para formas plurales» encontrarás las reglas de plural para diferentes idiomas.

text: qsTr("%n second(s)", "seconds", root.seconds)

Muestra la configuración regional actual y utiliza qsTr() para traducir el texto de origen «Locale: %1». Además, la traducción debe contener la notación de argumento «%1». De este modo, el argumento del texto (es decir, Qt.locale().name) se puede utilizar correctamente para dar formato al texto:

text: qsTr("Locale: %1").arg(Qt.locale().name)

Da formato a la hora y la fecha según las convenciones de la configuración regional. Los distintos países pueden tener preferencias específicas sobre cómo deben presentarse la hora y la fecha. Por ejemplo, la configuración regional alemana utiliza el formato de 24 horas y escribe el día antes del mes, mientras que la configuración regional de EE. UU. sigue el formato de 12 horas y coloca el mes antes del día. El método `Date.toLocaleTimeString` tiene en cuenta estas consideraciones y formatea la hora y la fecha correctamente en función de la configuración regional especificada:

            const now = new Date();
            const locale = Qt.locale();
            root.time = now.toLocaleTimeString(locale, Locale.ShortFormat);
            root.date = now.toLocaleDateString(locale);

Proyecto de ejemplo en @code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.