qt_add_translations

Qt Linguist 의 .ts 파일을 .qm 파일로 변환하고 업데이트할 대상을 추가합니다.

이 명령어는 Qt6 패키지의 LinguistTools 컴포넌트에 정의되어 있습니다. 다음 명령어로 패키지를 불러오십시오:

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

이 명령어는 Qt 6.2에서 도입되었습니다.

개요

Qt 6.7부터:

qt_add_translations([target]
                    [TARGETS target1 [target2...]]
                    [SOURCE_TARGETS target1 [target2...]]
                    [TS_FILE_BASE name]
                    [TS_FILES file1.ts [file2.ts ...]]
                    [PLURALS_TS_FILE file.ts]
                    [NO_GENERATE_PLURALS_TS_FILE]
                    [RESOURCE_PREFIX prefix]
                    [OUTPUT_TARGETS variable-name]
                    [TS_FILES_OUTPUT_VARIABLE variable-name]    # since 6.8
                    [TS_OUTPUT_DIRECTORY directory]             # since 6.9
                    [QM_FILES_OUTPUT_VARIABLE variable-name]
                    [QM_OUTPUT_DIRECTORY directory]             # since 6.9
                    [SOURCES source1.cpp [sources2.cpp ...]]
                    [INCLUDE_DIRECTORIES directory1 [directory2 ...]]
                    [LUPDATE_TARGET target-name]
                    [LUPDATE_OPTIONS ...]
                    [LRELEASE_TARGET target-name]
                    [LRELEASE_OPTIONS ...]
                    [MERGE_QT_TRANSLATIONS]
                    [QT_TRANSLATION_CATALOGS catalog1 [catalog2 ...]]
                    [IMMEDIATE_CALL])

Qt 6.2부터 (사용 중단됨):

qt_add_translations(target TS_FILES file1.ts [file2.ts ...]
                    [RESOURCE_PREFIX prefix]
                    [OUTPUT_TARGETS variable-name]
                    [QM_FILES_OUTPUT_VARIABLE variable-name]
                    [SOURCES source1.cpp [sources2.cpp ...]]
                    [INCLUDE_DIRECTORIES directory1 [directory2 ...]]
                    [LUPDATE_OPTIONS ...]
                    [LRELEASE_OPTIONS ...])

버전 정보가 없는 명령어가 비활성화된 경우, 대신 qt6_add_translations() 를 사용하십시오. 이 명령어는 본 명령어와 동일한 인자 집합을 지원합니다.

설명

Qt Linguist .ts 파일을 업데이트하고 이를 .qm 파일로 변환하기 위한 타깃을 생성합니다. 이 함수는 qt_add_lupdate() 및 qt_add_lrelease() 를 감싸는 편의 래퍼이며, 두 함수의 가장 일반적인 사용법을 한 번의 호출로 제공하도록 설계되었습니다.

TARGETS 매개변수는 실행 시 생성된 .qm 파일을 로드할 대상의 목록을 지정합니다. 해당 대상이 하나뿐인 경우, 첫 번째 인자로 대상 이름을 직접 전달할 수 있습니다.

SOURCE_TARGETS 매개변수는 번역 가능한 문자열이 포함된 소스 코드를 가진 실행 파일 또는 라이브러리 타깃의 목록을 지정합니다. 이 타깃들의 소스 코드를 바탕으로 .ts 파일이 생성됩니다.

SOURCE_TARGETS 가 지정되지 않은 경우, PROJECT_SOURCE_DIR 의 디렉터리 범위 끝에서 qt_collect_translation_source_targets()를 호출하여 타겟을 자동으로 수집합니다. 이 기능을 사용하려면 CMake 3.19 이상이 필요합니다. 이 기능은 IMMEDIATE_CALL 인수를 사용하여 비활성화할 수 있습니다.

이 함수는 update_translations 타깃을 생성하며, 이 타깃은 lupdate 를 사용하여 모든 소스 파일을 스캔하고 .ts 파일을 생성 및 업데이트합니다.

이 함수는 .ts 파일로부터 .qm 파일을 생성하는 release_translations 타깃을 생성합니다. 이 타깃은 기본적으로 빌드됩니다.

.ts 파일은 TS_FILES 인수를 사용하여 지정할 수 있지만, qt_add_translations 가 파일 경로를 자동으로 파악하도록 하는 것이 더 편리합니다. 자세한 내용은 .ts 파일 경로의 자동 결정 항목을 참조하십시오.

소스 및 포함 디렉터리

SOURCES 를 사용하면 번역 가능한 문자열이 포함된 추가 소스 파일을 명시적으로 지정할 수 있습니다.

INCLUDE_DIRECTORIES 를 사용하여 해당 소스 파일의 포함 디렉터리를 명시적으로 지정할 수 있습니다.

.ts 파일 경로의 자동 파악

QT_I18N_TRANSLATED_LANGUAGES가 설정되어 있으면, qt_add_translations 의 입력으로 사용되는 .ts 파일의 경로를 자동으로 파악할 수 있습니다. 이 변수는 qt_standard_project_setup()을 사용하여 편리하게 설정할 수 있습니다.

일반적으로 다음과 같은 프로젝트 설정이면 충분합니다:

project(myproject)
cmake_minimum_required(VERSION 3.19)
find_package(Qt6 COMPONENTS Core LinguistTools)
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

add_subdirectory(libs)
add_subdirectory(apps)

qt_add_translations(TARGETS myapp)

이렇게 하면 프로젝트의 소스 디렉터리에 myproject_de.ts 및 myproject_fr.ts 파일이 생성됩니다.

기본적으로 .ts 파일은 CMAKE_CURRENT_SOURCE_DIR 디렉터리에 생성됩니다. TS_OUTPUT_DIRECTORY 인수를 통해 다른 디렉터리를 지정하여 위치를 변경할 수 있습니다.

기본적으로 .ts 파일 이름은 PROJECT_NAME 을 기반으로 생성됩니다. TS_FILE_BASE 인수를 사용하여 다른 기본 이름을 지정할 수 있습니다.

Qt 6.8부터는 TS_FILES_OUTPUT_VARIABLE 인수를 지정하여 자동으로 결정된 .ts 파일 경로를 변수에 저장할 수 있습니다.

Qt 6.9 이전에는 TS_OUTPUT_DIRECTORY 인수가 TS_FILE_DIR 이라고 불렸습니다. 이 이름은 기존 프로젝트 파일이 계속 작동할 수 있도록 TS_OUTPUT_DIRECTORY 의 별칭으로 여전히 사용되고 있습니다.

복수형

QT_I18N_SOURCE_LANGUAGE는 소스 코드 문자열이 작성된 언어를 지정합니다. 복수형을 올바르게 처리하려면, 해당 언어에 대해 복수형에 대한 번역 가능한 문자열만 포함하는 별도의 .ts 파일을 생성하십시오. 자세한 내용은 복수형 처리를 참조하십시오.

PLURALS_TS_FILE 를 사용하면 소스 언어에 대한 .ts 파일을 지정할 수 있습니다. 이 파일에는 복수형만 포함됩니다.

NO_GENERATE_PLURALS_TS_FILE 옵션이 지정되지 않은 경우, 복수형 전용 .ts 파일이 자동으로 생성됩니다.

소스 언어의 전체 번역이 필요한 경우, 이를 QT_I18N_TRANSLATED_LANGUAGES에 추가하십시오.

예를 들어,

project(myapp)
qt_standard_project_setup(
    I18N_SOURCE_LANGUAGE en         # optional - this is the default
    I18N_TRANSLATED_LANGUAGES de
)
qt_add_executable(myapp ...)
...
qt_add_translations(myapp)

전체 번역 파일 myapp_de.ts 과 복수형 전용 파일 myapp_en.ts 이 생성됩니다.

옵션

LUPDATE_TARGET 옵션을 사용하여 lupdate를 호출하는 사용자 정의 타깃의 이름을 지정할 수 있습니다. 마찬가지로, LRELEASE_TARGET 는 lrelease 호출을 제어하는 사용자 정의 타깃의 이름을 제어합니다.

LUPDATE_OPTIONS 및 LRELEASE_OPTIONS 을 사용하여 lupdate와 lrelease에 대한 추가 옵션을 설정할 수 있습니다. 사용 가능한 옵션은 lupdate 옵션 및 lrelease 옵션에서 확인할 수 있습니다.

생성된 .qm 파일의 위치

기본적으로 .qm 파일은 현재 빌드 디렉터리(CMAKE_CURRENT_BINARY_DIR)에 저장됩니다. Qt 6.9부터는 QM_OUTPUT_DIRECTORY 인수를 사용하여 .qm 파일을 다른 디렉터리에 생성할 수 있습니다. 상대 경로는 CMAKE_CURRENT_BINARY_DIR 아래에 있는 것으로 간주됩니다.

예를 들어, 다음 코드를 사용하면 .qm 파일이 현재 빌드 디렉터리 아래의 translations 디렉터리에 생성됩니다.

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

보다 세밀한 제어를 위해, 해당 .ts 파일의 소스 파일 속성인 OUTPUT_LOCATION 을 설정하여 개별 .qm 파일의 출력 디렉터리를 지정할 수 있습니다. 이는 qt_add_translations 을 호출하기 전에 수행해야 합니다.

OUTPUT_LOCATION 소스 파일 속성은 QM_OUTPUT_DIRECTORY 를 통해 전달된 디렉터리를 재정의합니다.

예를 들어, 다음 코드를 사용하면 .qm 파일들이 현재 빌드 디렉터리 아래의 translations 디렉터리에 생성됩니다.

set_source_files_properties(app_en.ts app_de.ts
    PROPERTIES OUTPUT_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/translations")
qt_add_translations(app)

생성된 .qm 파일을 리소스에 삽입하기

기본적으로 생성된 .qm 파일은 TARGETS 를 통해 전달된 타깃에 링크될 Qt 리소스에 포함됩니다. 리소스 내의 파일은 리소스 접두사 "/i18n" 아래에서 액세스할 수 있습니다.

RESOURCE_PREFIX 를 사용하여 리소스 접두사를 설정할 수 있습니다.

정적 Qt 빌드에서 리소스 타깃이 생성될 때, 추가 타깃이 생성될 수 있습니다. OUTPUT_TARGETS <variable-name> 를 전달하여 qt_add_translations 가 이러한 타깃을 변수에 저장하도록 지시할 수 있습니다.

OUTPUT_TARGETS 를 사용하는 경우, IMMEDIATE_CALL 또는 SOURCE_TARGETS 중 하나를 반드시 지정해야 합니다.

QM_FILES_OUTPUT_VARIABLE 옵션을 지정한 뒤, 명령어가 생성된 .qm 파일 목록을 저장할 변수 이름을 이어서 지정하면 자동 리소스 삽입 기능을 끌 수 있습니다.

qt_add_translations Qt 6.7 이전

Qt 6.7 이전에는 이 명령이 첫 번째 인수로 하나의 타깃만 허용했습니다. 이 타깃은 번역 가능한 소스 추출과 .qm 파일 삽입 모두에 사용되었습니다.

Qt 6.7부터는 첫 번째 인수의 타깃이 소스 추출에 더 이상 사용되지 않습니다.

Qt에서 제공하는 번역 병합

Qt 6.9부터는 Qt에서 제공하는 번역을 애플리케이션 전용 .qm 파일에 병합할 수 있습니다. 이를 위해 qt_add_translations 에 MERGE_QT_TRANSLATIONS 옵션을 전달하십시오. 그러면 프로젝트에서 사용하는 모듈에 속한 Qt 번역 카탈로그가 식별되어, lrelease 가 생성한 .qm 파일에 병합됩니다.

Qt 번역 카탈로그는 qt_add_translations 가 호출되는 CMakeLists.txt 범위 내의 find_package 호출에 의해 결정됩니다. 예를 들어, 다음 시퀀스는 qtbase 및 qtmultimedia 카탈로그를 .qm 파일에 병합합니다:

find_package(Qt6 COMPONENTS MultimediaWidgets)
...
qt_add_translations(my_app MERGE_QT_TRANSLATIONS)

카탈로그를 명시적으로 지정하려면 QT_TRANSLATION_CATALOGS 인수를 사용하십시오:

qt_add_translations(my_app
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase qtmultimedia
)

프로젝트에서 Qt가 자체 번역을 제공하지 않는 언어를 지원하는 경우, configure 단계에서 경고가 발생합니다. CMake 변수 QT_NO_MISSING_CATALOG_LANGUAGE_WARNING 을 ON 로 설정하면 이 경고를 억제할 수 있습니다.

.ts 파일 이름의 자동 판별 기능이 사용되지 않는 경우, 각 .ts 파일에 대해 QT_I18N_TRANSLATED_LANGUAGES 소스 파일 속성이 설정되어 있는지 반드시 확인해야 합니다.

예시

qt_add_translations 를 사용하여 대상 frogger 에 독일어 및 프랑스어 번역을 추가합니다:

cmake_minimum_required(VERSION 3.28)
project(frogger)
find_package(Qt6 COMPONENTS OpenGLWidgets)
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

# The CMake files in the 'src' subdirectory create
# the targets 'frogger_game' and 'frogger_level_editor'.
add_subdirectory(src)

# Add translations to the 'frogger_game' target.
qt_add_translations(frogger_game)

이렇게 하면 소스 디렉터리에 frogger_de.ts 및 frogger_fr.ts 라는 .ts 파일이 생성됩니다. lupdate는 qt_collect_translation_source_targets()의 규칙에 따라 번역 대상인 모든 타깃의 소스 파일을 식별합니다.

.ts 파일에서 생성된 .qm 파일들은 리소스 접두사 "i18n" 하위의 frogger_game 타깃에 포함됩니다.

위 예제의 qt_add_translations 호출은 대략 다음과 동일합니다.

qt_collect_translation_source_targets(i18n_targets)
qt_add_lupdate(
    SOURCE_TARGETS ${i18n_targets}
    TS_FILES frogger_de.ts frogger_fr.ts)
qt_add_lrelease(
    TS_FILES frogger_de.ts frogger_fr.ts
    QM_FILES_OUTPUT_VARIABLE qm_files)
qt_add_resources(frogger_game "translations"
    PREFIX "/i18n"
    BASE "${CMAKE_CURRENT_BINARY_DIR}"
    FILES "${qm_files}"
)

디렉터리, 타깃 및 소스 제외

소스 타깃의 자동 수집에서 타깃과 디렉터리를 제외할 수 있습니다. 다음은 helper_lib 타깃과 tests 디렉터리 아래의 모든 항목을 제외합니다. 디렉터리 속성 QT_EXCLUDE_FROM_TRANSLATION 및 타깃 속성 QT_EXCLUDE_FROM_TRANSLATION을 참조하십시오.

# <project_root>/CMakeLists.txt
qt_add_translations(frogger_game)

# <project_root>/src/helper_lib/CMakeLists.txt
qt_add_library(helper_lib STATIC helpers.cpp)
set_property(TARGET helper_lib PROPERTY QT_EXCLUDE_FROM_TRANSLATION ON)

# <project_root>/tests/CMakeLists.txt
add_subdirectory(behavior_tests)
add_subdirectory(physics_tests)
set_directory_properties(PROPERTIES QT_EXCLUDE_FROM_TRANSLATION ON)

다음 예제에서는 QT_EXCLUDE_SOURCES_FROM_TRANSLATION 타깃 속성을 사용하여 frogger_game 타깃에 포함된 소스 파일을 제외합니다.

qt_add_executable(frogger_game
    main.cpp
    3rdparty/jumpsim.cpp
    3rdparty/frogmath.cpp
)
set_property(TARGET frogger_game
    PROPERTY QT_EXCLUDE_SOURCES_FROM_TRANSLATION "3rdparty/*"
)

소스 타깃의 명시적 지정

소스 타깃의 자동 수집 기능을 사용하지 않으려면 소스 타깃을 명시적으로 지정할 수 있습니다:

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

사용자 정의 리소스 접두사

이제 .qm 파일을 frogger_game 및 frogger_level_editor 에 포함시키고 사용자 정의 리소스 접두사를 설정해 보겠습니다.

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    RESOURCE_PREFIX "/translations"
)

.qm 파일 설치

.qm 파일을 포함하는 대신 일반 파일로 설치할 수도 있습니다:

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    QM_FILES_OUTPUT_VARIABLE qm_files
)
install(FILES ${qm_files} DESTINATION "translations")

.ts 파일 이름 지정

.ts 파일을 translations 디렉터리에 배치하고 기본 이름을 frogger_i18n 로 변경합니다:

qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)
...
qt_add_translations(frogger
    TS_FILE_BASE froggo
    TS_OUTPUT_DIRECTORY translations
)

이렇게 하면 다음과 같은 파일이 생성됩니다

• translations/froggo_de.ts
• translations/froggo_fr.ts

경로를 명시적으로 지정할 수도 있습니다:

qt_add_translations(frogger
    TS_FILES translations/froggo_de.ts translations/froggo_fr.ts
)