메타 문자열 참조
메타 문자열은 번역 처리를 위해 lupdate 및 Qt Linguist 에 추가 정보를 제공하는 특수한 주석입니다. 메타 문자열은 특정 접두사를 사용하여 용도를 식별하며, C++, QML 및 Python 코드에서 사용할 수 있습니다.
메타 문자열 구문 개요
메타 문자열은 특정 접두사를 사용하여 lupdate에 번역에 관한 추가 정보를 제공하는 특수한 주석입니다:
| 메타 문자열 | 목적 | 사용법 |
|---|---|---|
//: | 번역가를 위한 추가 설명 | 번역가에게 맥락과 지침을 제공하여 도움을 줍니다 |
//% | 원문 (엔지니어링 영어) | 개발 과정에서 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>라벨(//@)
//@ 메타 문자열을 사용하여 Qt Linguist 내에서 ID 기반 번역을 논리적인 그룹이나 범주로 정리하십시오. 이는 번역 문자열이 많은 대규모 프로젝트에서 특히 유용합니다.
참고: //@ 메타문자열은 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은 ID 기반 번역(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 매직 주석
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 contextTS 파일 형식
TRANSLATOR 주석은 <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.