diff --git a/api_review_qt_6_7_part2.md b/api_review_qt_6_7_part2.md index 4246bf741725a4de78f928ad53eec4ae56213bb0..17cbe752692c47ad039b9a221ef4f07899f59183 100644 --- a/api_review_qt_6_7_part2.md +++ b/api_review_qt_6_7_part2.md @@ -1,7 +1,7 @@ # Task and links https://bugreports.qt.io/browse/QTBUG-121136 -https://git.qt.io/alcroito/qt6-cmake-api-review/-/blob/master/api_review_qt_6_7.md +https://git.qt.io/alcroito/qt6-cmake-api-review/-/blob/master/api_review_qt_6_7_part2.md # Changes @@ -84,152 +84,6 @@ AP: Update example snippet with something richer AP: Update `NATIVE_TS_FILE` to `PLURALS_TS_FILE` -### `qt_add_lrelease` - New API options and changed option - -Make the target argument of `qt_add_lrelease` optional. -Passing a target as the first argument to -`qt_add_lrelease` was deprecated. - -https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-lrelease.html - -https://codereview.qt-project.org/c/qt/qttools/+/496435 - -Old signature - -```cmake -qt_add_lrelease(target TS_FILES file1.ts [file2.ts ...] - [NO_TARGET_DEPENDENCY] -``` - -New signature - -```cmake -qt_add_lrelease(TS_FILES file1.ts [file2.ts ...] - [LRELEASE_TARGET target-name] - [EXCLUDE_FROM_ALL] -``` - -Documented. -No specific example snippet. -No "since qt version" blurb for new / changed options. -`NO_TARGET_DEPENDENCY` disappeared from docs, not mentioned in deprecated section. -First `target` option that is now deprecated IS documented. - -**Notes:** - -**Action points:** - - - -### `qt_add_lupdate` - New API options and changed option - -Allow specifying multiple targets in `qt_add_lupdate` - -https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-lupdate.html - -https://codereview.qt-project.org/c/qt/qttools/+/495546 - -Old signature - -```cmake -qt_add_lupdate(target TS_FILES file1.ts [file2.ts ...] -``` - -New signature - -```cmake -qt_add_lupdate(TS_FILES file1.ts [file2.ts ...] - [TARGETS target1 [target2 ...]] -``` - -Documented. -No specific example snippet. -No "since qt version" blurb for new / changed options. -First `target` option that is now deprecated IS documented. - -**Notes:** - -**Action points:** - - - -### `qt_collect_i18n_targets` - New API - -Add `qt_collect_i18n_targets`, collects targets that are eligible for translation. - -https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-collect-targets-for-translation.html - -https://codereview.qt-project.org/c/qt/qttools/+/496434 - -Signature - -```cmake -qt_collect_i18n_targets(out_var [DIRECTORY path]) -``` - -Documented. -Has "since qt version" blurb. -Has example snippet. - -**Notes:** - -**Action points:** - - - -### `QT_EXCLUDE_FROM_TRANSLATION` - New target and directory properties - -Targets can be excluded from translation by setting the target property -`QT_EXCLUDE_FROM_TRANSLATION` to TRUE - -Targets below a certain directory can be excluded from translation by -setting the directory property `QT_EXCLUDE_FROM_TRANSLATION` to TRUE. - -https://doc-snapshots.qt.io/qt6-dev/cmake-directory-property-qt-exclude-from-translation.html -https://doc-snapshots.qt.io/qt6-dev/cmake-target-property-qt-exclude-from-translation.html - -https://codereview.qt-project.org/c/qt/qttools/+/496434 - -Documented. -Has "since qt version" blurb. -No example snippets. - -**Notes:** - -**Action points:** - - - -### `QT_EXCLUDE_SOURCES_FROM_TRANSLATION` - New target property - -Allow excluding target sources from i18n. -The target property -`QT_EXCLUDE_SOURCES_FROM_TRANSLATION` was added to exclude source files of -a target from handling with lupdate. - -https://doc-snapshots.qt.io/qt6-dev/cmake-target-property-qt-exclude-sources-from-translation.html - -https://codereview.qt-project.org/c/qt/qttools/+/498913 - -Signature - -```cmake -set_property(TARGET myapp PROPERTY QT_EXCLUDE_SOURCES_FROM_TRANSLATION - untranslatable.cpp - 3rdparty/* -) -``` - -Documented. -Has "since qt version" blurb. -Has example snippet. - -**Notes:** - -**Action points:** - - - ### `qt_add_translations` - New API options and behavior change @@ -280,118 +134,3 @@ https://doc.qt.io/qt-6/linguist-id-based-i18n.html AP: Mention idbased option on qt_add_translations doc page, and link to page above just mention `LRELEASE_OPTIONS -idbased` AP: Kai: Talk to qt design team why they use idbased translations - -### `qt_add_translations` - New API options and behavior change - -Automatically determine `.ts` file names in `qt_add_translations` - -The `TS_FILES` argument of `qt_add_translations` is -optional now, and .ts file paths can be automatically determined after -setting the `QT_I18N_LANGUAGES` variable. - -https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-translations.html - -https://codereview.qt-project.org/c/qt/qttools/+/501634 - -Old signature - -```cmake -qt_add_translations([target] - TS_FILES file1.ts [file2.ts ...] -``` - -New signature - -```cmake -qt_add_translations([target] - [TS_FILE_BASE name] - [TS_FILE_DIR directory] - [TS_FILES file1.ts [file2.ts ...]] -``` - -Documented. -Has example snippet. -No "since qt version" blurb for new options. - - -**Notes:** - -**Action points:** - - - -### `qt_add_translations` - Behavior change - -Automatically determine the path of the native .ts file - -If the `TS_FILES` argument is not passed to -`qt_add_translations`, the path to the native .ts file is automatically -determined if `QT_I18N_NATIVE_LANGUAGE` variable is set. - -https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-translations.html - -https://codereview.qt-project.org/c/qt/qttools/+/503733 - -Documented. -No example / comparison snippet. -No "since qt version" blurb for new options. - -**Notes:** - -**Action points:** - - -### `qt_add_lupdate` - New API options and behavior change - -Add a way to specify the native language for i18n - -https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-translations.html - -https://codereview.qt-project.org/c/qt/qttools/+/502121 - - -Old signature - -```cmake -qt_add_lupdate(TS_FILES file1.ts [file2.ts ...] -``` - -New signature - -```cmake -qt_add_lupdate(TS_FILES file1.ts [file2.ts ...] - [NATIVE_TS_FILE file.ts] -``` - -Documented. -No example snippet. -No "since qt version" blurb for new options. - - -**Notes:** - -**Action points:** - - - -### Overall translations documentation page - -We are missing a more general adding translations page after all the new API was added. - -The most prominent CMake one is - -https://doc-snapshots.qt.io/qt6-dev/cmake-get-started.html#adding-translations - -which is quite short. - -And the generic ones at - -https://doc-snapshots.qt.io/qt6-dev/internationalization.html -https://doc-snapshots.qt.io/qt6-dev/localization.html - -don't mention very much about build systems. - - -**Notes:** - -**Action points:** diff --git a/api_review_qt_6_7_part3.md b/api_review_qt_6_7_part3.md new file mode 100644 index 0000000000000000000000000000000000000000..e8917e57a70ead3de8e400442caf84c830c0bf8e --- /dev/null +++ b/api_review_qt_6_7_part3.md @@ -0,0 +1,322 @@ +# Task and links + +https://bugreports.qt.io/browse/QTBUG-121136 +https://git.qt.io/alcroito/qt6-cmake-api-review/-/blob/master/api_review_qt_6_7_part3.md + +# Changes + + + +## qttools + +### `qt_add_lrelease` - New API options and changed option + +Make the target argument of `qt_add_lrelease` optional. +Passing a target as the first argument to +`qt_add_lrelease` was deprecated. + +https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-lrelease.html + +https://codereview.qt-project.org/c/qt/qttools/+/496435 + +Old signature + +```cmake +qt_add_lrelease(target TS_FILES file1.ts [file2.ts ...] + [NO_TARGET_DEPENDENCY] +``` + +New signature + +```cmake +qt_add_lrelease(TS_FILES file1.ts [file2.ts ...] + [LRELEASE_TARGET target-name] + [EXCLUDE_FROM_ALL] +``` + +Documented. +No specific example snippet. +No "since qt version" blurb for new / changed options. +`NO_TARGET_DEPENDENCY` disappeared from docs, not mentioned in deprecated section. +First `target` option that is now deprecated IS documented. + +**Notes:** + +**Action points:** + + + +### `qt_add_lupdate` - New API options and changed option + +Allow specifying multiple targets in `qt_add_lupdate` + +https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-lupdate.html + +https://codereview.qt-project.org/c/qt/qttools/+/495546 + +Old signature + +```cmake +qt_add_lupdate(target TS_FILES file1.ts [file2.ts ...] +``` + +New signature + +```cmake +qt_add_lupdate(TS_FILES file1.ts [file2.ts ...] + [TARGETS target1 [target2 ...]] +``` + +Documented. +No specific example snippet. +No "since qt version" blurb for new / changed options. +First `target` option that is now deprecated IS documented. + +**Notes:** + +**Action points:** + + + +### `qt_collect_i18n_targets` - New API + +Add `qt_collect_i18n_targets`, collects targets that are eligible for translation. + +https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-collect-targets-for-translation.html + +https://codereview.qt-project.org/c/qt/qttools/+/496434 + +Signature + +```cmake +qt_collect_i18n_targets(out_var [DIRECTORY path]) +``` + +Documented. +Has "since qt version" blurb. +Has example snippet. + +**Notes:** + +**Action points:** + + + +### `QT_EXCLUDE_FROM_TRANSLATION` - New target and directory properties + +Targets can be excluded from translation by setting the target property +`QT_EXCLUDE_FROM_TRANSLATION` to TRUE + +Targets below a certain directory can be excluded from translation by +setting the directory property `QT_EXCLUDE_FROM_TRANSLATION` to TRUE. + +https://doc-snapshots.qt.io/qt6-dev/cmake-directory-property-qt-exclude-from-translation.html +https://doc-snapshots.qt.io/qt6-dev/cmake-target-property-qt-exclude-from-translation.html + +https://codereview.qt-project.org/c/qt/qttools/+/496434 + +Documented. +Has "since qt version" blurb. +No example snippets. + +**Notes:** + +**Action points:** + + + +### `QT_EXCLUDE_SOURCES_FROM_TRANSLATION` - New target property + +Allow excluding target sources from i18n. +The target property +`QT_EXCLUDE_SOURCES_FROM_TRANSLATION` was added to exclude source files of +a target from handling with lupdate. + +https://doc-snapshots.qt.io/qt6-dev/cmake-target-property-qt-exclude-sources-from-translation.html + +https://codereview.qt-project.org/c/qt/qttools/+/498913 + +Signature + +```cmake +set_property(TARGET myapp PROPERTY QT_EXCLUDE_SOURCES_FROM_TRANSLATION + untranslatable.cpp + 3rdparty/* +) +``` + +Documented. +Has "since qt version" blurb. +Has example snippet. + +**Notes:** + +**Action points:** + + + + +### `qt_add_translations` - New API options and behavior change + +Support project-wide i18n with `qt_add_translations`. +Gained the `TARGETS` argument to specify multiple targets that intend to load .qm files. + +Gained the `SOURCE_TARGETS` argument to specify multiple targets that contain sources with +translatable strings. + +If the first argument of `qt_add_translations` is a target, that target is not used +anymore for extracting translatable sources. + +Now defers itself to the end of the scope of `PROJECT_SOURCE_DIR` if `SOURCE_TARGETS` is not given. +This behavior can be turned off by passing `IMMEDIATE_CALL`. + +https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-translations.html + +https://codereview.qt-project.org/c/qt/qttools/+/498033 + +Old signature + +```cmake +qt_add_translations(target TS_FILES file1.ts [file2.ts ...] +``` + +New signature + +```cmake +qt_add_translations([target] + [TARGETS target1 [target2...]] + [SOURCE_TARGETS target1 [target2...]] + TS_FILES file1.ts [file2.ts ...] + [IMMEDIATE_CALL]) +``` + +Documented. +No `IMMEDIATE_CALL` example snippet. +Partial "since qt version" blurb for new / changed options. + +**Notes:** + +**Action points:** +AP: There is a use case to pass in extra qm files (e.g qt sdk translations) to +`qt_add_translations` to merge them, currently not released, open gerrit change, +possibly in Qt 6.8. +AP: Look into what happens when id-based translations are mixed with regular translations +https://doc.qt.io/qt-6/linguist-id-based-i18n.html +AP: Mention idbased option on qt_add_translations doc page, and link to page above +just mention `LRELEASE_OPTIONS -idbased` +AP: Kai: Talk to qt design team why they use idbased translations + +### `qt_add_translations` - New API options and behavior change + +Automatically determine `.ts` file names in `qt_add_translations` + +The `TS_FILES` argument of `qt_add_translations` is +optional now, and .ts file paths can be automatically determined after +setting the `QT_I18N_LANGUAGES` variable. + +https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-translations.html + +https://codereview.qt-project.org/c/qt/qttools/+/501634 + +Old signature + +```cmake +qt_add_translations([target] + TS_FILES file1.ts [file2.ts ...] +``` + +New signature + +```cmake +qt_add_translations([target] + [TS_FILE_BASE name] + [TS_FILE_DIR directory] + [TS_FILES file1.ts [file2.ts ...]] +``` + +Documented. +Has example snippet. +No "since qt version" blurb for new options. + + +**Notes:** + +**Action points:** + + + +### `qt_add_translations` - Behavior change + +Automatically determine the path of the native .ts file + +If the `TS_FILES` argument is not passed to +`qt_add_translations`, the path to the native .ts file is automatically +determined if `QT_I18N_NATIVE_LANGUAGE` variable is set. + +https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-translations.html + +https://codereview.qt-project.org/c/qt/qttools/+/503733 + +Documented. +No example / comparison snippet. +No "since qt version" blurb for new options. + +**Notes:** + +**Action points:** + + +### `qt_add_lupdate` - New API options and behavior change + +Add a way to specify the native language for i18n + +https://doc-snapshots.qt.io/qt6-dev/qtlinguist-cmake-qt-add-translations.html + +https://codereview.qt-project.org/c/qt/qttools/+/502121 + + +Old signature + +```cmake +qt_add_lupdate(TS_FILES file1.ts [file2.ts ...] +``` + +New signature + +```cmake +qt_add_lupdate(TS_FILES file1.ts [file2.ts ...] + [NATIVE_TS_FILE file.ts] +``` + +Documented. +No example snippet. +No "since qt version" blurb for new options. + + +**Notes:** + +**Action points:** + + + +### Overall translations documentation page + +We are missing a more general adding translations page after all the new API was added. + +The most prominent CMake one is + +https://doc-snapshots.qt.io/qt6-dev/cmake-get-started.html#adding-translations + +which is quite short. + +And the generic ones at + +https://doc-snapshots.qt.io/qt6-dev/internationalization.html +https://doc-snapshots.qt.io/qt6-dev/localization.html + +don't mention very much about build systems. + + +**Notes:** + +**Action points:**