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()をラップした利便性を高めるための関数であり、1回の呼び出しで両関数の最も一般的な使用法を提供することを目的としています。

パラメータ `TARGETS ` は、実行時に生成された `.qm ` ファイルをロードするターゲットのリストを指定します。そのようなターゲットが 1 つしかない場合は、最初の引数としてそのターゲット名を直接渡すことができます。

パラメータ `SOURCE_TARGETS ` は、翻訳可能な文字列を含むソースを持つ実行ファイルまたはライブラリ・ターゲットのリストを指定します。これらのターゲットのソースから、.ts ファイルが生成されます。

SOURCE_TARGETS が指定されていない場合、PROJECT_SOURCE_DIR のディレクトリスコープの末尾でqt_collect_translation_source_targets()を呼び出すことにより、ターゲットが自動的に収集されます。この機能を利用するには、CMake 3.19以降が必要です。この機能は、引数IMMEDIATE_CALL を指定することで無効にできます。

この関数は、update_translations というターゲットを作成します。このターゲットは、lupdate を使用してすべてのソースファイルをスキャンし、.ts ファイルを作成・更新します。

この関数は、ターゲット `release_translations ` を作成します。このターゲットは、`.ts ` ファイルから `.qm ` ファイルを生成します。このターゲットはデフォルトでビルドされます。

.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 以前では、このコマンドは最初の引数として 1 つのターゲットのみを受け付けていました。このターゲットは、翻訳可能なソースの抽出と.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)

これにより、ソースディレクトリに.ts ファイルであるfrogger_de.ts およびfrogger_fr.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
)