En esta página

Referencia de metacadenas

Las meta-cadenas son comentarios especiales que proporcionan información adicional a lupdate y Qt Linguist para el procesamiento de la traducción. Utilizan prefijos específicos para identificar su finalidad y pueden utilizarse en código C++, QML y Python.

Resumen de la sintaxis de las meta-cadenas

Las meta-cadenas son comentarios especiales que utilizan prefijos específicos para proporcionar a lupdate información adicional sobre las traducciones:

Meta-cadenaFinalidadUso
//:Comentario adicional para los traductoresProporciona contexto y orientación para ayudar a los traductores
//%Texto original (inglés técnico)Define el texto que se mostrará en las traducciones basadas en ID durante el desarrollo
//@Etiqueta para la agrupaciónOrganiza las traducciones basadas en ID en grupos lógicos
//~Metadatos adicionales de clave-valorAlmacena información personalizada adicional sobre la traducción
// TRANSLATORComentario mágico para el contextoProporciona información contextual sobre la clase o el archivo

Nota: La cadena meta « //= » para la asignación de ID de mensajes ha quedado obsoleta y no debe utilizarse en código nuevo.

Comentarios del traductor (//:)

Utiliza comentarios « //: » para proporcionar contexto adicional y orientación a los traductores. Estos comentarios aparecen en la interfaz de traducción de Qt Linguist y ayudan a los traductores a comprender el significado y el uso del texto.

Ejemplo en C++

//: Button to navigate backwards in the application
tr("Back");

//: This is a file menu item that opens an existing document.
//: Keep translation short to fit in menu.
tr("Open");

Ejemplo en QML

Button {
  //: Emergency stop button - must be clearly visible
  text: qsTr("STOP")
}

Ejemplo en Python

#: Button to navigate backwards in the application
self.tr("Back")

#: This is a file menu item that opens an existing document.
#: Keep translation short to fit in menu.
self.tr("Open")

Se pueden utilizar varios comentarios del traductor para la misma cadena y se concatenarán con saltos de línea en el archivo TS.

Formato del archivo TS

Los comentarios de los traductores aparecen como elementos « <extracomment> » en el archivo TS:

<message>
    <source>Back</source>
    <extracomment>Button to navigate backwards in the application</extracomment>
    <translation type="unfinished"></translation>
</message>

Texto original (//%)

La metacadena « //% » define el texto en inglés técnico que aparece en la interfaz de usuario durante el desarrollo cuando se utilizan traducciones basadas en identificadores. Esto es esencial para que la aplicación sea utilizable antes de que se completen las traducciones.

Ejemplo en C++

//% "Save Document"
qtTrId("file.save");

//% "Found %n items"
qtTrId("search.results", count);

Ejemplo en QML

Text {
  //% "Welcome to the application"
  text: qsTrId("welcome.message")
}

Notas importantes

  • Incluye marcadores de posición de parámetros (%1, %n) en el texto de origen
  • El texto original debe estar listo para su uso en producción y estar redactado en inglés
  • Sin comentarios //%, el propio ID del texto aparecerá en la interfaz de usuario

Formato de archivo TS

El texto de origen aparece como el elemento « <source> »:

<message id="file.save">
    <source>Save Document</source>
    <translation type="unfinished"></translation>
</message>

Etiquetas (//@)

Utiliza las metasecuencias « //@ » para organizar las traducciones basadas en ID en grupos o categorías lógicas dentro de Qt Linguist. Esto resulta especialmente útil para proyectos de gran envergadura con numerosas cadenas de traducción.

Nota: La meta-cadena « //@ » está pensada únicamente para traducciones basadas en ID (qtTrId/qsTrId) y no debe utilizarse con traducciones basadas en texto (tr/qsTr).

Ejemplo en C++

//% "New Document"
//@ FileOperations
qtTrId("file.new");

//% "Print Document"
//@ FileOperations
qtTrId("file.print");

//% "Connection failed"
//@ NetworkErrors
qtTrId("network.error.connection");

Ejemplo en QML

Button {
  //% "Login"
  //@ Authentication
  text: qsTrId("auth.login")
}

Nota: Las etiquetas no son aplicables a las traducciones de Python, ya que Python solo admite traducciones basadas en texto (self.tr()) y no traducciones basadas en ID.

Las cadenas con la misma etiqueta aparecen agrupadas en Qt Linguist, lo que facilita a los traductores trabajar en contenidos relacionados.

Para la generación automática de etiquetas mediante marcadores de posición como <context>, <class>, <file> y sus combinaciones, consulta Generación automática de etiquetas.

Formato de archivo TS

Las etiquetas aparecen como un elemento label:

<message id="file.new" label="FileOperations">
    <source>New Document</source>
    <label>FileOperations</label>
    <translation type="unfinished"></translation>
</message>

Metadatos adicionales (//~)

La cadena de metadatos //~ permite adjuntar metadatos arbitrarios de tipo clave-valor a las traducciones. Esto puede utilizarse para el procesamiento personalizado o como orientación para los traductores.

Sintaxis

//~ key value
//~ key "quoted value with spaces"

Ejemplo en C++

//% "Error"
//: Critical system error dialog
//~ Severity High
//~ MaxLength "20"
//~ Context "Error dialogs"
qtTrId("system.error");

Ejemplo en QML

Text {
  //% "Loading..."
  //~ Context "Progress indicators"
  //~ ShowDuration "true"
  text: qsTrId("progress.loading")
}

Ejemplo en Python

#~ Severity High
#~ Context "Error dialogs"
self.tr("Critical system error")

Formato de archivo TS

Los metadatos adicionales aparecen como elementos « <extra-*> » en el archivo TS y pueden procesarse mediante herramientas personalizadas o flujos de trabajo de traducción.

<message id="system.error">
    <source>Error</source>
    <comment>Critical system error dialog</comment>
    <translation type="unfinished"></translation>
    <extra-Severity>High</extra-Severity>
    <extra-MaxLength>20</extra-MaxLength>
    <extra-Context>Error dialogs</extra-Context>
</message>

Claves adicionales reconocidas

Aunque se puede utilizar cualquier clave con « //~ », la bandera « no-wrap » dentro de « po-flags » es reconocida por « lconvert ». Véanse las opciones específicas del formato PO.

Comentarios mágicos de TRANSLATOR

TRANSLATOR Los comentarios proporcionan información contextual sobre una clase o un archivo fuente para ayudar a los traductores a comprender dónde se utilizan las traducciones.

Ejemplo en C++

/*
  TRANSLATOR MainWindow

  This class contains the main application window interface.
  All menu items and toolbar buttons are defined here.
*/
class MainWindow : public QMainWindow
{
  // ... translations for this context
};

Ejemplo en QML

// TRANSLATOR LoginDialog Login dialog for user authentication
Item {
  Text {
      text: qsTr("Username")
  }
}

Ejemplo en Python

# TRANSLATOR MainWindow
#
# Main application window containing the primary user interface.
# Keep button labels concise due to space constraints.
#
class MainWindow(QMainWindow):
  def setupUi(self):
      self.tr("File")  # translations for this context

Formato de archivo TS

Los comentarios TRANSLATOR aparecen como elementos ` <message> ` con texto fuente vacío en el elemento ` <context> `:

<context>
    <name>Main</name>
    <message>
        <source></source>
        <comment>LoginDialog Login dialog for user authentication</comment>
        <translation></translation>
    </message>
</context>

Combinación de metacadenas

Las metacadenas se pueden combinar para proporcionar metadatos de traducción completos:

Ejemplo completo en C++

//: File dialog - confirm destructive action
//: This will permanently delete the selected files
//% "Delete Selected Files"
//@ FileOperations
//~ Severity High
//~ RequiresConfirmation "true"
qtTrId("file.delete.confirm");

Ejemplo completo en QML

Text {
  //: Shows current connection status to server
  //: Updates automatically every few seconds
  //% "Connected to server"
  //@ NetworkStatus
  //~ UpdateFrequency "5000ms"
  //~ Color "green"
  text: qsTrId("status.connected")
}

Buenas prácticas

  • Utiliza generosamente los comentarios del traductor (//:) para proporcionar contexto
  • Incluye siempre el texto de origen (//%) para las traducciones basadas en identificadores
  • Agrupa las traducciones relacionadas utilizando etiquetas (//@) en proyectos de gran envergadura
  • Coloca las cadenas meta inmediatamente antes de la llamada a la función de traducción
  • Mantén los comentarios del traductor claros y concisos, pero informativos
  • Utiliza una nomenclatura coherente para las etiquetas y las claves de metadatos adicionales

© 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.