텍스트 ID 기반 번역

텍스트 ID 번역 메커니즘은 국제화 및 현지화를 위한 산업급 시스템입니다. 애플리케이션의 각 텍스트에는 고유 식별자(텍스트 ID)가 부여되며, 소스 코드에서는 텍스트 대신 이 식별자를 사용합니다. 이를 통해 대량의 번역된 텍스트를 훨씬 쉽게 관리할 수 있습니다.

텍스트 ID를 활용한 국제화

일반 텍스트 대신 텍스트 ID를 사용할 때, 애플리케이션을 국제화하는 일반적인 방법은 동일하지만 세부 사항은 약간 다릅니다:

1. 텍스트 ID 기반 번역 시스템을 위한 함수와 매크로는 일반 텍스트 시스템과 다릅니다. qsTr() 대신 qsTrId() 함수를, QT_TR_NOOP() 대신 QT_TRID_NOOP() 매크로를, QT_TR_N_NOOP()) 대신 QT_TRID_N_NOOP() 매크로를 사용합니다.
2. 텍스트 ID를 일반 텍스트 문자열 대신 사용자 인터페이스 문자열로 사용하십시오. 예를 들어, qsTrId("id-back-not-front")
3. 텍스트 ID로는 컨텍스트 매개변수를 지정할 수 없으므로, 철자는 같지만 의미가 다른 단어에는 별도의 텍스트 ID가 필요합니다. 예를 들어, qsTrId("id-back-backstep") 은 뒤로 이동하는 ‘Back’과 ‘ id-back-not-front ’의 ‘Back’을 구분합니다.
4. 텍스트 ID 기반 번역에서는 컨텍스트 이름을 사용할 수 없으므로, Qt Linguist 는 컨텍스트 이름 없이 파일에 ID를 나열합니다.
5. 개발 빌드용 사용자 인터페이스에 표시되는 엔지니어링 영어 텍스트는 ` //% ` 주석으로 표시됩니다. 이를 포함하지 않으면 텍스트 ID가 사용자 인터페이스에 표시됩니다. 이는 매개변수가 포함된 텍스트가 있을 때 특히 중요합니다. ` //% ` 주석에는 문자열 내에 매개변수 표시자가 포함되어야 합니다. 예를 들어, //% "Number of files: %1"
6. 번역가에게 추가 정보를 제공하는 //: 주석은 일반 텍스트 시스템에서는 선택 사항입니다. 그러나 텍스트 ID 기반 시스템에서는 이 추가 정보가 필수적입니다. 이 정보가 없으면 텍스트 ID만 남게 되며, 번역가는 추가적인 문맥 정보 없이는 이를 바탕으로 적절한 번역을 수행하기 어려울 수 있기 때문입니다. 길고 설명적인 텍스트 ID를 사용하고 주석을 생략할 수도 있지만, 주석이 있는 쪽이 이해하기 더 쉬운 경우가 많습니다.

아래의 나란히 배치된 코드 스니펫은 텍스트 ID 기반 번역과 일반 텍스트 기반 번역의 비교를 보여줍니다:

Text {
    id: backTxt;
    //: The back of the object, not the front
    //% "Back"
    //~ Context Not related to back-stepping
    text: qsTrId("id-back-not-front");
}

Text {
    id: backTxt;
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back","Not front")
}

텍스트 ID를 사용한 현지화

텍스트 ID를 사용한 현지화는 일반 텍스트와 거의 동일한 과정을 따릅니다.

lupdate 도구를 사용하여 TS 파일을 생성한 다음, 해당 파일에 번역 내용을 추가합니다. 번역 파일의 원본 값은 일반 텍스트가 아닌 텍스트 ID이므로, 번역의 정확성을 보장하기 위해서는 설명적인 텍스트 ID나 명확한 추가 주석, 또는 둘 다 필요합니다.

위의 텍스트 ID 기반 사용자 인터페이스 텍스트 예시는 .ts 파일에 다음과 같은 내용을 생성합니다:

<message id="id-back-not-front">
    <source>Back</source>
    <extracomment>The back of the object, not the front</extracomment>
    <translation type="unfinished"></translation>
    <extra-Context>Not related to back-stepping</extra-Context>
</message>

특정 텍스트에 대한 번역이 없는 경우(일반적으로 개발 후반부까지는 이런 경우가 많습니다), 사용자 인터페이스에는 적절한 텍스트 대신 텍스트 ID가 표시됩니다. 테스트 시 애플리케이션의 사용성을 높이기 위해, lrelease 에서 ‘엔지니어링 영어’ 원문( //% 주석에서 가져온)을 번역된 텍스트로 사용하도록 설정하고, 감탄표(!)와 같은 표시를 추가하여 아직 번역되지 않은 텍스트를 쉽게 식별할 수 있도록 할 수 있습니다.

ID 기반 번역 그룹화

각 ID 기반 번역에 레이블을 할당하여 대규모 프로젝트의 ID 기반 항목을 더 작은 그룹으로 정리할 수 있습니다. ID 기반 항목에 레이블을 할당하려면, 레이블 이름을 명시한 //@ 주석을 추가하면 됩니다. 예를 들어 C++에서는 다음과 같습니다:

//% "Open file"
//@ FileOperations
qtTrId("msg.open");

또는 QML의 경우:

//% "Open file"
//@ FileOperations
qsTrId("msg.open");

TS 파일을 열면 Qt Linguist에서 TS 파일을 열면, 동일한 레이블을 가진 ID 기반 항목들이 문맥별로 그룹화되는 텍스트 기반 항목과 유사하게 함께 묶입니다. 레이블이 없는 항목은 ` <unnamed label>` 아래에 표시됩니다.

자동 라벨 생성

라벨 이름을 수동으로 지정하는 대신, 자리 표시자를 사용하여 코드 구조를 기반으로 라벨을 자동으로 생성할 수 있습니다:

• //@ <context> - 전체 컨텍스트(네임스페이스::클래스)를 자동으로 사용합니다.
• //@ <class> - 클래스 이름만 자동으로 사용합니다(네임스페이스 제외)
• //@ <file> - 소스 파일 이름을 자동으로 사용합니다

자리 표시자 결합

플레이스홀더를 사용자 정의 텍스트와 결합하여 더 설명적인 레이블을 만들 수 있습니다:

• //@ <file>:<class> - 파일명과 클래스 결합: filehandler.cpp:FileHandler
• //@ <context>_customSuffix - 접미사 추가: MyApp::FileHandler_customSuffix
• //@ module_<file>_<class>-label - 사용자 정의 접두사 및 접미사: module_filehandler.cpp_FileHandler-label
• //@ <context>:<file> - 파일과 관련된 맥락: MyApp::FileHandler:filehandler.cpp

예를 들어, C++에서는:

namespace MyApp {
class FileHandler : QObject {
    Q_OBJECT
    void open() {
        //% "Open file"
        //@ <context>
        qtTrId("msg.open"); // Label: MyApp::FileHandler

        //% "Save file"
        //@ <class>
        qtTrId("msg.save"); // Label: FileHandler

        //% "Export"
        //@ <file>
        qtTrId("msg.export"); // Label: filehandler.cpp
    }
};
}

또는 QML에서는:

Item {
    id: myComponent
    Component.onCompleted: {
        //% "Loading"
        //@ <context>
        qsTrId("msg.loading") // Label: <component-name>

        //% "Ready"
        //@ <file>
        qsTrId("msg.ready") // Label: main.qml

        //% "Initialized"
        //@ <file>:<context>-state
        qsTrId("msg.init") // Label: main.qml:<component-name>-state
    }
}

자동 레이블은 많은 파일에서 레이블 이름을 수동으로 관리하는 것이 번거로울 수 있는 대규모 프로젝트에서 특히 유용합니다. 이는 코드 구조를 기반으로 일관된 그룹화를 보장하며, 번역가에게 해당 번역이 어디에 사용될지에 대한 힌트를 제공합니다.

CMake 구성

CMake로 빌드할 때는 .ts 파일에 qml_ 접두사를 사용하십시오. 예를 들어, qml_en.ts 와 같이 합니다. CMakeLists.txt 파일에서 qt_add_translations 함수를 추가하고, TS_FILES 의 값으로 *.ts 파일들을 나열하며, RESOURCE_PREFIX의 값을 프로젝트의 main.qml 파일 URI 뒤에 /i18n:을 붙여 설정하십시오:

qt_add_translations(${CMAKE_PROJECT_NAME}
    TS_FILES i18n/qml_de_DE.ts i18n/qml_en_US.ts
    RESOURCE_PREFIX Main/i18n
)

qmake를 이용한 고급 사용법

많은 로케일을 대상으로 하는 프로젝트의 경우, .pro 파일에서 TRANSLATIONS 정보를 제거하고 대신 별도의 스크립트를 통해 번역을 관리할 수 있습니다. 이 스크립트는 원하는 각 타깃에 대해 lrelease 및 lupdate 를 호출할 수 있습니다.

업데이트는 다음과 같이 스크립트로 작성할 수 있습니다:

lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_GB.ts
lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_US.ts
...

최종 .qm 파일 생성은 다음과 같이 스크립트로 작성할 수 있습니다:

lrelease <project-dir>/i18n/myapp-text_en_GB.ts
lrelease <project-dir>/i18n/myapp-text_en_US.ts
...