En esta página

Reloj localizado con traducción basada en el ID

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

Interfaz de usuario

El ejemplo muestra la hora y la fecha actuales según la configuración regional y el idioma de tu sistema. Se admiten traducciones en 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.

El ejemplo también admite una configuración regional como argumento de la línea de comandos para probar diferentes idiomas y configuraciones regionales sin modificar el sistema: localizedClockIdBased --locale en_GB o localizedClockIdBased --locale de

De forma predeterminada, la aplicación muestra la hora y la fecha en la configuración regional actual, pero también ofrece un botón que abre un cuadro de diálogo con una lista de zonas horarias. El usuario puede utilizar el cuadro de diálogo para cambiar la zona horaria del reloj.

Traducción basada en ID

En este ejemplo, utilizamos la traducción basada en ID, en la que los textos traducibles se identifican mediante un ID único en lugar de la combinación tradicional de contexto + texto (véase Traducciones basadas en ID de texto). Este enfoque permite reutilizar las traducciones en diferentes contextos. Lo demostramos compartiendo una traducción entre Main.qml y el cuadro de diálogo «Time Zone», un formulario basado en « QWidget » escrito en C++. Otro aspecto de la traducción basada en ID es que separa el texto que se muestra en la interfaz de usuario del código fuente, lo que hace que este último sea independiente de las palabras concretas que se presentan al usuario.

En las dos capturas de pantalla siguientes de la aplicación en inglés, las dos instancias del texto «Seleccionar zona horaria: » en la ventana principal (QML) y en el cuadro de diálogo (C++) comparten la misma traducción al utilizar el mismo ID.

Captura de pantalla de la ventana de la aplicación en la versión en inglés:

El cuadro de diálogo con una lista de zonas horarias (versión en inglés):

La ventana principal de la aplicación en alemán:

El cuadro de diálogo con la lista de zonas horarias (versión en alemán):

Implementación

La aplicación consta de cinco partes:

CMakeLists.txt

El archivo CMake de la aplicación habilita la traducción y la localización basadas en identificadores 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, incluido Linguist, esenciales para la internacionalización. qt_standard_project_setup(): Configura el sistema de internacionalización con soporte para las configuraciones regionales enumeradas. Aunque el idioma de origen es el inglés, sigue siendo necesaria una traducción al inglés cuando se utiliza la traducción basada en ID. El código fuente solo contiene los ID y no tiene acceso a los textos originales. Por lo tanto, debemos configurar el proyecto con la traducción al inglés, de modo que `qt_add_translations` cree un archivo TS para el inglés; de lo contrario, faltarán en tiempo de ejecución.

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

qt_add_translations(...): Agrupa las funcionalidades 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.

  • Genera un archivo TS por cada idioma que aparece en I18N_TRANSLATED_LANGUAGES de qt_standard_project_setup.
  • MERGE_QT_TRANSLATIONS y QT_TRANSLATION_CATALOGS qtbase incluyen las traducciones de Qt en el proyecto. Esto es necesario para traducir los botones del widget QDialog en el cuadro de diálogo de zonas horarias. Dado que el texto de esos botones está controlado por QDialog, si no se incluyen las traducciones de Qt, dichos botones no se traducen (véanse los textos traducidos del cuadro de diálogo en las capturas de pantalla en alemán en «Traducción basada en ID»).
qt_add_translations(localizedClockIdBased
    TS_FILE_BASE i18n/clock
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase
    RESOURCE_PREFIX i18n
)

qt_add_qml_module(...): Añade un módulo QML bajo la URI qtexamples.localizedclock, incluye el archivo Main.qml e importa los archivos fuente y de cabecera de Time Zone Manager al módulo QML.

qt_add_qml_module(localizedClockIdBased
    URI qtexamples.localizedclock
    VERSION 1.0
    QML_FILES
        Main.qml
    RESOURCES dialog.ui
    SOURCES
        timezonemanager.h timezonemanager.cpp
        dialog.h dialog.cpp
)
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 se han instalado:

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

Instalar una traducción según la configuración regional indicada:

    QTranslator traducción;
    if (QLocale().language() != QLocale::English) {
        if (translation.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()));
        }
    }

Como hemos instalado la traducción al inglés 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.

Cuadro de diálogo de zona horaria

Esta clase es un cuadro de diálogo en C++ basado en « QWidget » (QDialog) que muestra un « QComboBox » con una lista de zonas horarias. A continuación se explica el código:

Habilitar la traducción basada en ID en el formulario de la interfaz de usuario (dialog.ui):

<ui version="4.0" idbasedtr="true">

Establecer el título con traducción basada en ID (dialog.ui). En este caso, «title» es el ID único de la traducción:

<property name="windowTitle">
    <string id="title">Time Zone</string>
</property>

Añade una etiqueta con traducción basada en el ID (dialog.ui), con el ID «timezonelabel»:

<widget class="QLabel" name="label">
...
<property name="text">
<string id="timezonelabel">Select time zone</string>
</property>
...
</widget>
Gestor de zonas horarias

Una clase de « QML_SINGLETON » en « C++ » encargada de gestionar los cambios de zona horaria.

Cuando el usuario selecciona una zona horaria, la instancia de ` TimeZoneManager ` recuerda la zona horaria elegida:

        connect(m_dialog.get(), &Dialog::timeZoneSelected, this, &TimeZoneManager::setTimeZone);

Al actualizar la zona horaria se emite una señal TimeZoneManager::timeZoneChanged:

        connect(m_dialog.get(), &Dialog::timeZoneSelected, this, &TimeZoneManager::setTimeZone);
    }
    m_dialog->show();
}

TimeZoneManager::currentTimeZoneOffsetMs() está marcado con « Q_INVOKABLE » y devuelve la diferencia horaria de la zona horaria seleccionada. Dado que la clase « TimeZoneManager » está declarada con « QML_ELEMENT » y «QML_SINGLETON», se puede acceder directamente al método desde QML para actualizar la hora que se muestra; véase también Main.qml.

qint64 TimeZoneManager::currentTimeZoneOffsetMs()
{
    const QTimeZone tz(m_timeZone.toLatin1());
    if (!tz.isValid())
        return 0;
    const QDateTime nowUtc = QDateTime::currentDateTimeUtc();

    const int targetOffset = tz.offsetFromUtc(nowUtc);
    const int systemOffset = QTimeZone::systemTimeZone().offsetFromUtc(nowUtc);

    return (targetOffset - systemOffset) * 1000;
}
Main.qml

El archivo QML principal define la interfaz de usuario de la aplicación. La interfaz muestra la hora, la fecha, la zona horaria actual y un contador de segundos. También incluye un botón que abre un cuadro de diálogo de zona horaria para cambiar la zona horaria. A continuación se explica el código relevante:

Define la ventana y establece su título utilizando qsTrId() para la traducción basada en ID. El texto del idioma de origen se especifica mediante la notación de meta-cadenas //% (véase «Traducciones basadas en ID de texto»). lupdate analiza las meta-cadenas y escribe los textos de origen definidos en el archivo TS. Dado que el texto de origen se especifica mediante meta-cadenas y en forma de comentario, no es visible para la aplicación en tiempo de ejecución. Por lo tanto, cuando la aplicación se carga con la configuración regional de inglés, aunque el idioma de origen sea el inglés, sigue siendo necesario instalar la traducción al inglés para mostrar los textos en inglés. De lo contrario, se muestra el ID sin formato «Main-Digital-Clock». Esta es también la razón por la que especificamos «en» en I18N_TRANSLATED_LANGUAGES mediante la configuración en CMakeLists.txt.

//% "Digital Clock"
title: qsTrId("Main-Digital-Clock")

Mostrar el número de segundos utilizando qsTrId() con soporte para el plural. De nuevo, aquí el texto en el idioma de origen se especifica utilizando la meta-cadena //%. La forma plural se habilita utilizando la notación especial «%n» en el texto de origen de la meta-cadena (véase «Manejo de 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.

//% "%n second(s)"
text: qsTrId("Main-n-second-s", root.seconds)

Muestra la zona horaria seleccionada actualmente mediante traducción basada en ID, donde //% "Time zone: " especifica el texto en el idioma de origen:

//% "Time zone: "
text: qsTrId("timezone") + TimeZoneManager.timeZone;

Un botón para abrir el cuadro de diálogo «Zona horaria». El texto del botón se especifica mediante qsTrId() para la traducción basada en ID. En este caso, el texto de origen ya no se define mediante metacadenas, ya que se reutiliza el ID «timezonelabel», que se había utilizado anteriormente en el documento dialog.ui (véase Cuadro de diálogo «Zona horaria»). En la traducción basada en ID, basta con especificar el texto de origen por ID una sola vez en el proyecto:

        Button {
            text: qsTrId("timezonelabel")
            onClicked: TimeZoneManager.openDialog()
            Layout.alignment: Qt.AlignHCenter
        }

Al cambiar la zona horaria y recibir la señal TimeZoneManager::timeZoneChanged() (véase «Gestor de zonas horarias»), actualiza la variable ` diff ` con la diferencia horaria de la zona horaria seleccionada:

    Connections {
        target: TimeZoneManager
        function onTimeZoneChanged() {
            root.diff = TimeZoneManager.currentTimeZoneOffsetMs();
        }
    }

Declare un temporizador que se active cada segundo y actualice las propiedades de hora, fecha y segundos. El temporizador calcula la hora sumando la hora actual a la diferencia horaria de la zona horaria seleccionada:

    Timer {
        interval: 1000
        running: true
        repeat: true
        triggeredOnStart: true

        onTriggered: {
            const now = new Date(new Date().getTime() + root.diff);
            const locale = Qt.locale();
            root.time = now.toLocaleTimeString(locale, Locale.ShortFormat);
            root.date = now.toLocaleDateString(locale);
            root.seconds = now.getSeconds();
        }
    }

La configuración regional 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 utiliza el formato de hora de 24 horas y el formato de fecha DD.MM.AAAA, mientras que una configuración regional de EE. UU. utiliza el formato de hora de 12 horas y el formato de fecha MM/DD/AAAA.

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.