Referencia a las metacadenas

Las metacadenas son comentarios especiales que proporcionan información adicional a lupdate y Qt Linguist para el proceso de traducción. Utilizan prefijos específicos para identificar su propósito y pueden utilizarse en código C++, QML y Python.

Sinopsis de la sintaxis de las metacadenas

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

Comentarios del traductor (//:)

Utilice los comentarios de //: 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 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 de 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 nuevas líneas en el archivo TS.

Formato del archivo TS

Los comentarios del traductor aparecen como elementos de <extracomment> en el archivo TS:

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

Texto fuente (//%)

La meta cadena //% define el texto en inglés de ingeniería que aparece en la interfaz de usuario durante el desarrollo cuando se utilizan traducciones basadas en ID. Esto es esencial para que la aplicación pueda utilizarse antes de que se completen las traducciones.

Ejemplo C

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

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

Ejemplo QML

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

Notas importantes

• Incluya marcadores de posición de parámetros (%1, %n) en el texto fuente.
• El texto fuente debe estar en inglés listo para producción
• Sin comentarios //%, el propio ID del texto aparece en la interfaz de usuario

Formato de archivo TS

El texto fuente aparece como el elemento <source>:

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

Etiquetas (//@)

Utilice las metacadenas //@ para organizar las traducciones basadas en ID en grupos o categorías lógicas dentro de Qt Linguist. Esto resulta especialmente útil en proyectos grandes con muchas cadenas de traducción.

Ejemplo C

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

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

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

Ejemplo QML

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

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

Para la generación automática de etiquetas utilizando marcadores de posición como <context>, <class>, <file>, y sus combinaciones, véase 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 meta //~ permite adjuntar metadatos arbitrarios de clave-valor a las traducciones. Esto puede utilizarse para el procesamiento personalizado o para guiar al traductor.

Sintaxis

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

Ejemplo 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 extra aparecen como elementos de <extra-*> en el archivo TS y pueden ser procesados por 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 extra 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.

TRANSLATOR comentarios mágicos

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

Ejemplo 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 QML

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

Ejemplo 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 pueden combinarse para proporcionar metadatos de traducción completos:

Ejemplo completo de 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 de 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

• Utilice generosamente los comentarios del traductor (//:) para proporcionar contexto.
• Incluya siempre el texto de origen (//%) en las traducciones basadas en ID.
• Agrupe las traducciones relacionadas mediante etiquetas (//@) en proyectos grandes.
• Coloque las cadenas meta inmediatamente antes de la llamada a la función de traducción.
• Los comentarios del traductor deben ser claros y concisos, pero informativos.
• Utilizar una nomenclatura coherente para las etiquetas y las claves de metadatos adicionales