이 페이지에서

메타 문자열 참조

메타 문자열은 번역 처리를 위해 업데이트 및 Qt Linguist 에 추가 정보를 제공하는 특수 주석입니다. 메타 문자열은 특정 접두사를 사용하여 용도를 식별하며 C++, QML 및 Python 코드에서 사용할 수 있습니다.

메타 문자열 구문 개요

메타 문자열은 특정 접두사를 사용하여 번역에 대한 추가 정보를 업데이트에 제공하는 특수 주석입니다:

메타 문자열목적사용법
//:번역가를 위한 추가 주석번역가를 돕기 위한 컨텍스트 및 지침 제공
//%소스 텍스트(엔지니어링 영어)개발 중 ID 기반 번역의 표시 텍스트를 정의합니다.
//@그룹화용 레이블ID 기반 번역을 논리적인 그룹으로 구성합니다.
//~추가 키-값 메타데이터번역에 대한 추가 사용자 지정 정보 저장
// TRANSLATOR컨텍스트를 위한 매직 코멘트클래스 또는 파일에 대한 컨텍스트 정보를 제공합니다.

참고: 메시지 ID 매핑을 위한 //= 메타 문자열은 더 이상 사용되지 않으므로 새 코드에 사용해서는 안 됩니다.

번역자 댓글(//:)

번역가에게 추가 컨텍스트 및 안내를 제공하려면 //: 댓글을 사용하세요. 이러한 댓글은 Qt Linguist 번역 인터페이스에 표시되며 번역자가 텍스트의 의미와 사용법을 이해하는 데 도움이 됩니다.

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");

QML 예제

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

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")

동일한 문자열에 대해 여러 번역자 코멘트를 사용할 수 있으며 TS 파일에서 개행으로 연결됩니다.

TS 파일 형식

번역기 댓글은 TS 파일에서 <extracomment> 요소로 나타납니다:

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

소스 텍스트(//%)

//% 메타 문자열은 ID 기반 번역을 사용할 때 개발 중에 사용자 인터페이스에 표시되는 엔지니어링 영어 텍스트를 정의합니다. 이는 번역이 완료되기 전에 애플리케이션을 사용할 수 있도록 만드는 데 필수적입니다.

C++ 예제

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

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

QML 예제

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

중요 참고 사항

  • 소스 텍스트에 매개변수 자리 표시자(%1, %n)를 포함하세요.
  • 소스 텍스트는 프로덕션에 사용할 수 있는 영어여야 합니다.
  • 주석이 없으면 텍스트 ID 자체가 UI에 표시됩니다.

TS 파일 형식

소스 텍스트는 <source> 요소로 나타납니다:

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

레이블(//@)

//@ 메타 문자열을 사용하여 ID 기반 번역을 Qt Linguist 내의 논리적 그룹 또는 카테고리로 구성하세요. 이는 번역 문자열이 많은 대규모 프로젝트에 특히 유용합니다.

참고: //@ 메타 문자열은 ID 기반 번역(qtTrId/qsTrId)에만 사용되며 텍스트 기반 번역(tr/qsTr)과 함께 사용해서는 안 됩니다.

C++ 예제

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

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

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

QML 예제

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

참고: Python은 텍스트 기반 번역(self.tr())만 지원하고 ID 기반 번역은 지원하지 않으므로 Python 번역에는 레이블을 적용할 수 없습니다.

동일한 레이블을 가진 문자열은 Qt Linguist 에 함께 그룹화되어 표시되므로 번역가가 관련 콘텐츠에 대해 더 쉽게 작업할 수 있습니다.

<context>, <class>, <file> 와 같은 자리 표시자와 그 조합을 사용한 자동 레이블 생성에 대해서는 자동 레이블 생성을 참조하세요.

TS 파일 형식

레이블은 label 요소로 표시됩니다:

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

추가 메타데이터(//~)

//~ 메타 문자열을 사용하면 번역에 임의의 키-값 메타데이터를 첨부할 수 있습니다. 이는 사용자 지정 처리 또는 번역가 안내에 사용할 수 있습니다.

구문

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

C++ 예제

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

QML 예제

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

Python 예제

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

TS 파일 형식

추가 메타데이터는 TS 파일에서 <extra-*> 요소로 표시되며 사용자 지정 도구 또는 번역 워크플로우로 처리할 수 있습니다.

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

인식되는 추가 키

//~ 에는 모든 키를 사용할 수 있지만 po-flags 내의 no-wrap 플래그는 lconvert 에서 인식됩니다. PO 형식별 옵션을 참조하세요.

번역기 매직 코멘트

TRANSLATOR 주석은 클래스 또는 소스 파일에 대한 컨텍스트 정보를 제공하여 번역가가 번역이 사용된 위치를 이해하는 데 도움을 줍니다.

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
};

QML 예제

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

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

TS 파일 형식

번역기 주석은 <context> 요소에 빈 소스 텍스트가 있는 <message> 요소로 표시됩니다:

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

메타 문자열 결합하기

메타 문자열을 결합하여 포괄적인 번역 메타데이터를 제공할 수 있습니다:

전체 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");

전체 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")
}

모범 사례

  • 번역자 주석(//:)을 넉넉하게 사용하여 컨텍스트를 제공하세요.
  • ID 기반 번역에는 항상 소스 텍스트(//%)를 포함하세요.
  • 대규모 프로젝트에서 레이블(//@)을 사용하여 관련 번역을 그룹화하기
  • 번역 함수 호출 바로 앞에 메타 문자열 배치하기
  • 번역가 코멘트를 명확하고 간결하면서도 유익한 정보로 유지하세요.
  • 레이블과 추가 메타데이터 키에 일관된 이름을 사용하세요.

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