애플리케이션 현지화

애플리케이션을 현지화하는 단계에는 번역 가능한 애플리케이션을 생성하고, 번역을 위해 준비하며, 문자열을 번역하고, 출시된 애플리케이션을 위한 런타임 번역 파일을 생성하는 과정이 포함됩니다.

Qt Quick QML 및 Qt C++ 애플리케이션은 모두 동일한 기본 현지화 시스템( lupdate, lrelease)과 이 시스템에서 생성되는 번역 소스(TS) 파일 및 QM 파일을 사용합니다. 『Qt Linguist 』 매뉴얼에 설명된 대로, QML 및 C++ 코드 모두에 동일한 도구를 사용합니다.

심지어 동일한 애플리케이션 내에서 QML 및 C++ 소스 파일에 사용자 인터페이스 문자열을 모두 포함시킬 수도 있습니다. 시스템은 하나의 통합 번역 파일을 생성하며, QML 및 C++ 코드에서 해당 문자열에 접근할 수 있습니다.

국제화된 애플리케이션을 현지화하려면:

• Qt 프로젝트 파일에서 번역 소스 지정
• 번역 배포
• Qt 모듈 번역 사용

Qt 프로젝트 파일에서 번역 소스 지정하기

lupdate 및 lrelease 가 TS 및 QM 파일을 생성할 수 있도록 하려면, 애플리케이션 프로젝트 파일을 업데이트하여 번역할 텍스트가 포함된 소스 파일을 지정하십시오.

실행 시 로드할 언어를 결정하려면 TS 파일 이름에 ISO 언어 및 국가 코드를 사용하십시오. 자세한 내용은 ‘번역 활성화’를 참조하십시오.

lupdate 도구는 애플리케이션에서 사용자 인터페이스 문자열을 추출합니다. 이 도구는 기본적으로 모든 소스 코드가 UTF-8로 인코딩되어 있을 것으로 가정합니다. 자세한 내용은 ‘인코딩’을 참조하십시오.

CMake 사용

Qt6LinguistTools 패키지를 불러와 Qt의 국제화용 CMake 명령을 사용할 수 있도록 합니다.

cmake_minimum_required(VERSION 3.16)
project(myproject)
find_package(Qt6 COMPONENTS Core LinguistTools)

qt_standard_project_setup()의 I18N_TRANSLATED_LANGUAGES 인수를 사용하여 지원되는 언어를 선언하십시오.

# Declare that the project will have a German and a French translation.
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

소스 코드에는 영어로 된 번역 가능한 문자열이 포함되어 있는 것으로 가정합니다. qt_standard_project_setup 매개변수 I18N_SOURCE_LANGUAGE 를 사용하여 소스 코드 내 문자열의 언어를 조정할 수 있습니다.

실행 시점에 ` .qm ` 파일을 불러와야 하는 대상에 대해 ` qt_add_translations() ` 명령을 호출하십시오.

qt_add_translations(myapplication)

해당 파일이 아직 존재하지 않는 경우, 이 명령을 실행하면 myproject_de.ts 및 myproject_fr.ts 파일이 생성됩니다. 파일 이름이 어떻게 구성되는지에 대해서는 .ts 파일 경로의 자동 결정 항목을 참조하십시오.

이 명령어는 또한 복수형 전용 번역 파일인 myproject_en.ts 도 생성합니다. 자세한 내용은 복수형 처리 항목을 참조하십시오. NO_GENERATE_PLURALS_TS_FILE 인수를 사용하면 복수형 전용 파일의 생성을 비활성화할 수 있습니다.

프로젝트의 모든 타깃에 속한 모든 소스 파일은 .ts 파일 생성을 위한 입력으로 간주됩니다. 프로젝트의 타깃이 어떻게 수집되는지, 그리고 타깃이나 개별 소스 파일을 제외하는 방법에 대한 자세한 내용은 qt_add_translations() 참조 문서를 참조하십시오.

qmake 사용

qmake를 사용할 때는 .pro 파일의 SOURCES 또는 HEADERS 항목에 나열된 QML 소스 파일을 컴파일러에서 제외하도록 조건문을 설정하십시오.

SOURCES 변수는 C++ 소스 파일을 위한 것입니다. 여기에 QML이나 JavaScript 소스 파일을 나열하면, 컴파일러는 해당 파일을 마치 C++ 파일인 것처럼 빌드하려고 시도합니다. 이를 해결하기 위해 lupdate_only{...} 조건문을 사용하면, lupdate 도구는 .qml 파일을 인식하지만 C++ 컴파일러는 이를 무시하게 됩니다.

예를 들어, 다음 .pro 파일 코드 조각은 애플리케이션에 포함된 두 개의 .qml 파일을 지정합니다.

lupdate_only{
SOURCES = main.qml \
          MainPage.qml
}

와일드카드 일치를 사용하여 .qml 소스 파일을 지정할 수도 있습니다. 검색은 재귀적으로 수행되지 않으므로, UI 문자열이 포함된 소스 파일이 있는 각 디렉터리를 명시적으로 지정해야 합니다:

lupdate_only{
SOURCES = *.qml \
          *.js \
          content/*.qml \
          content/*.js
}

번역 배포

.qm 파일을 배포하는 가장 쉬운 방법은 이를 Qt 리소스에 포함시키는 것입니다. qt_add_translations() CMake 명령을 사용하면 이 작업이 자동으로 처리됩니다. .qm 파일은 ":/i18n" 리소스 접두사 아래에서 접근할 수 있습니다.

# Automatically embed generated .qm files.
qt_add_translations(myapplication)

또는 .qm 파일을 파일 시스템의 특정 디렉터리에 배포할 수도 있습니다. 이는 사용 가능한 모든 번역 내용을 메모리에 보관하고 싶지 않은 대규모 애플리케이션의 경우 바람직합니다. qt_add_translations()에 QM_FILES_OUTPUT_VARIABLE 인수를 전달하십시오. 이 명령어는 생성된 .qm 파일 목록을 지정된 변수에 저장합니다. 해당 목록에 있는 파일 이름에 대해 CMake의 일반적인 설치 명령어를 사용하십시오.

# Do not embed generated .qm files.
qt_add_translations(myapplication
    QM_FILES_OUTPUT_VARIABLE qm_files
)

# Install generated .qm files.
install(FILES ${qm_files} DESTINATION translations)

애플리케이션에 필요한 .qm 파일을 QTranslator 을 사용하는 로더 코드가 찾을 수 있는 위치에 배치하십시오. 일반적으로 QCoreApplication::applicationDirPath()을 기준으로 한 상대 경로를 지정합니다.

애플리케이션의 QM 파일 외에도, 시스템에 설치되어 있지 않은 경우 애플리케이션에서 사용하는 Qt 모듈에 대한 QM 파일도 배포해야 합니다.

QM 파일은 모듈별로 분리되어 있으며, 모든 모듈의 QM 파일을 포함하는 소위 메타 카탈로그 파일이 있습니다. 그러나 애플리케이션에서 사용하는 모듈에 대한 QM 파일만 배포하면 됩니다.

배포 단계에서 ‘ lconvert ’ 도구를 사용하여 필요한 QM 파일들을 메타 카탈로그 파일에 부합하는 하나의 파일로 결합할 수 있습니다. 예를 들어, Qt Core, Qt GUI, 및 Qt Quick 모듈을 사용하는 애플리케이션의 독일어 번역 파일을 생성하려면 다음 명령을 실행하십시오:

lconvert -o installation_folder/qt_de.qm qtbase_de.qm qtdeclarative_de.qm

Qt 모듈 번역 사용

Qt 모듈에는 대상 언어로 번역해야 할 수천 개의 문자열이 포함되어 있습니다. qttranslations 저장소에서 여러 TS 파일을 찾을 수 있습니다. Qt 번역을 시작하기 전에 위키 페이지 'Qt를 다른 언어로 번역하기'를 읽어보시기 바랍니다.

Qt 번역 파일 찾기

QLibraryInfo::path()를 사용하여 애플리케이션에서 사용하는 Qt 모듈의 번역 파일을 찾을 수 있습니다. 이 함수에 QLibraryInfo::TranslationsPath 를 전달하여 런타임 시 번역 파일의 경로를 요청할 수 있습니다.

사용 가능한 카탈로그

Qt 번역 카탈로그는 qttranslations 저장소에 있습니다.

Qt 4에서는 로케일당 하나의 거대한 단일 .qm 파일이 있습니다. 예를 들어, qt_de.qm 파일에는 모든 라이브러리의 독일어 번역이 포함되어 있습니다.

qt_ 메타 카탈로그는 Qt 4의 qt_ 카탈로그에 포함되어 있던, 현재도 여전히 존재하는 Qt 번역들을 담고 있습니다. 이 카탈로그는 Qt 4에서 Qt 5로 애플리케이션을 이식하는 과정을 용이하게 하기 위해 만들어졌습니다. 이 메타 카탈로그는 불필요하거나 더 이상 사용되지 않는 모듈에 속하여 존재하지 않을 수도 있는 번역에 의존하므로, 번역 로딩이 실패할 수 있습니다. 애플리케이션에서 Qt 5 이상 버전에서 새로 추가된 모듈을 사용하는 경우, 메타 카탈로그를 사용하더라도 해당 모듈에 대한 카탈로그 이름을 반드시 지정해야 합니다.

다음 표에는 Qt의 모듈 및 도구에 사용할 수 있는 번역 카탈로그가 나열되어 있습니다.

예시: 필수 Qt 모듈

예를 들어, Qt Core, Qt GUI, Qt Network, Qt Widgets 과 같은 필수 Qt 모듈의 번역본을 찾으려면, main() 함수에 다음 코드를 추가하십시오:

    QTranslator qtTranslator;
    if (qtTranslator.load(QLocale::system(), u"qtbase"_s, u"_"_s,
                          QLibraryInfo::path(QLibraryInfo::TranslationsPath))) {
        app.installTranslator(&qtTranslator);
    }