애플리케이션 현지화

애플리케이션을 로컬라이즈하는 단계에는 번역 가능한 애플리케이션 만들기, 번역 준비, 문자열 번역, 릴리스된 애플리케이션의 런타임 번역 파일 만들기 등이 포함됩니다.

Qt Quick 그리고 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 파일을 파일 시스템의 디렉터리에 배포할 수 있습니다. 이는 사용 가능한 모든 번역을 메모리에 보관하고 싶지 않은 대규모 애플리케이션에 적합합니다. QM_FILES_OUTPUT_VARIABLE 인수를 qt_add_translations에 전달합니다. 이 명령은 생성된 .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 모듈

예를 들어 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);
    }