Skip to content

Commit db238ae

Browse files
meatormeator
committed
Document translation process
1 parent 631c687 commit db238ae

1 file changed

Lines changed: 116 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,94 @@ To use linuxdeploy-plugin-standalone, download the official AppImage, make it ex
4545
linuxdeploy-plugin-qt will look for Qt libraries in the library directory `usr/lib/` and deploy the Qt plugins and other resources for these. This means that if linuxdeploy or another tool haven't been run on the AppDir yet, i.e., no Qt libraries have been deployed yet, linuxdeploy-plugin-qt won't be able to recognize which plugins and resources have to be deployed, and will return an error.
4646

4747

48+
### Translations
49+
#### Qt Translations
50+
Translation of Qt libraries (usually accessible at `/usr/share/qt{5,6}/translations/`) is split into the following categories:
51+
52+
| Category | CLI enable | CLI disable | Env variable |
53+
| ------------------------------- | --------------------------- | ------------------------------ | -------------------------------- |
54+
| Individual library translations | `--individual-translations` | `--no-individual-translations` | `TRANSLATIONS_INDIVIDUAL=YES/NO` |
55+
| Merged library translations | `--merged-translations` | `--no-merged-translations` | `TRANSLATIONS_MERGED=YES/NO` |
56+
57+
Individual library translations copy over individual `.qm` files into standard translation directory (`<AppDir>/share/translations`, retrievable by calling `QLibraryInfo::path(QLibraryInfo::TranslationsPath)` from within program). For example, if the program is using Core and Multimedia modules, `qtbase_cs.qm`, `qtmultimedia_cs.qm`, `qtbase_de.qm`, `qtmultimedia_de.qm`... will get copied over.
58+
59+
Merged library translations will produce a `qt_<lang>.qm` file into standard translation directory. This is consistent with for example how `windeployqt.exe` Qt official deployer deploys translations.
60+
61+
By default, all available translations matching the Qt libraries used are deployed. The list of deployed languages can be restricted by supplying a comma separated list of language codes (codes matching filenames in `/usr/share/qt{5,6}/translations/`) with `--qt-languages` or `$TRANSLATION_LANGUAGES`.
62+
63+
Note that `--qt-languages` and `$TRANSLATION_LANGUAGES` only affect Qt's own translations. Program provided translations are not affected.
64+
65+
#### App Translations
66+
App translation handling is program specific. For best results, make sure to configure the build system of the program to be deployed [as described in AppImage documentation](https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#using-the-build-system-to-build-the-basic-appdir) when deploying from source.
67+
68+
It is best to test translations before distributing the AppImage. This can be done by
69+
70+
1. Making sure the locale to be tested is loaded on glibc Linux
71+
72+
Here are some resources on the topic: [Arch Linux (Arch Wiki)](https://wiki.archlinux.org/title/Locale), [Debian](https://wiki.debian.org/Locale), [Alpine](https://wiki.alpinelinux.org/wiki/Locale), [Void Linux](https://docs.voidlinux.org/config/locales.html), [Gentoo](https://wiki.gentoo.org/wiki/Localization/Guide).
73+
2. Override the `LC_MESSAGES` or `LANG` variable while executing the appimage from a terminal by either prepending `<VAR>=<LANG> ./myappimage.AppImage`:
74+
75+
```
76+
LC_MESSAGES=cs_CZ.UTF-8 ./myappimage-x86_64.AppImage
77+
```
78+
79+
or by issuing `export` before running the AppImage:
80+
81+
```
82+
export LC_MESSAGES=cs_CZ.UTF-8
83+
./myappimage-x86_64.AppImage
84+
```
85+
86+
Make sure that the tested program does indeed provide translations for the overridden locale.
87+
88+
linuxdeploy-plugin-qt provides a flag to add a symlink to program translations to `TranslationsPath` (to `<AppDir>/usr/translations`):
89+
90+
| Category | CLI enable | CLI disable | Env variable |
91+
| ------------------------------- | ---------------------------- | ------------------------------- | --------------------------------- |
92+
| Symlink app translations | `--app-symlink-translations` | `--no-app-symlink-translations` | `TRANSLATIONS_SYMLINK_APP=YES/NO` |
93+
94+
#### Recommendations
95+
linuxdeploy-plugin-qt enables individual library translations and symlink app translations and disabled merged library translations by default for backwards compatibility.
96+
97+
If the program was written with for example with `windeployqt.exe` in mind, merged library translations and symlink app translations should do the job.
98+
99+
You can try enabling and disabling these flags to see which are required for the program being packaged to load translations.
100+
101+
#### Recommendations to application developers
102+
Load Qt translations with
103+
104+
```cpp
105+
translator.load("qt_" + language, QLibraryInfo::path(QLibraryInfo::TranslationsPath));
106+
```
107+
108+
or
109+
110+
```cpp
111+
translator.load(QLocale::system(), "qt", "_", QLibraryInfo::path(QLibraryInfo::TranslationsPath));
112+
```
113+
114+
This should work with linux distro packages, `windeployqt` deployed `.exe` files and with linuxdeploy-plugin-qt.
115+
116+
For program translations, the easiest way of distributing translations in regard to deploying it (with linuxdeploy-plugin-qt or other tools) is to bundle them into the executable as a [Qt resource](https://doc.qt.io/qt-6/resources.html). The rest of this section concerns the more complicated solution, which is installing compiled translations alongside the executable.
117+
118+
For program translations, you have the freedom of choosing translation directory, but be aware that the [recommended building process](https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#using-the-build-system-to-build-the-basic-appdir) uses prefix of `/usr` and `DESTDIR` to install program files into AppDir.
119+
120+
If you try to load translations from the directory your build system thinks it installs them into at configure time, it will try to load translations from host, not from the appimage.
121+
122+
One solution is to load directories relative to `QLibraryInfo::path(QLibraryInfo::PrefixPath)` instead of `/usr` or build system prefix. See [standard paths](#standard-paths) for a list of standard paths recognized by Qt.
123+
124+
Another solution is to load from path relative to `QCoreApplication::applicationDirPath()`.
125+
126+
It is wise to try several directories for loading app translations. Some reasonable picks include:
127+
128+
```cpp
129+
// Good for windeployqt and macdeployqt
130+
QLibraryInfo::path(QLibraryInfo::TranslationsPath)
131+
// windeployqt-esque
132+
QCoreApplication::applicationDirPath() + "/translations"
133+
// Not Windows friendly, good in combination with some other dirs
134+
QLibraryInfo::path(QLibraryInfo::PrefixPath) + "/share/" + QCoreApplication::applicationName() + "/translations"
135+
```
48136
49137
### Environment variables
50138
@@ -62,6 +150,34 @@ Just like all linuxdeploy plugins, the Qt plugin's behavior can be configured so
62150
- `$EXTRA_PLATFORM_PLUGINS=platformA;platformB`: Platforms to deploy in addition to `libqxcb.so`. Platform must be available from `QT_INSTALL_PLUGINS/platforms`.
63151
- To support Wayland, add `libqwayland-egl.so;libqwayland-generic.so`
64152
153+
**Translations:**
154+
- `$TRANSLATIONS_INDIVIDUAL=YES/NO`
155+
- `$TRANSLATIONS_MERGED=YES/NO`
156+
- `$TRANSLATIONS_SYMLINK_APP=YES/NO`
157+
- `$TRANSLATION_LANGUAGES=comma separated language list`
158+
159+
See [translations](#translations) for an explanation of the env variables.
160+
65161
QML related:
66162
- `$QML_SOURCES_PATHS`: directory containing the application's QML files — useful/needed if QML files are "baked" into the binaries. linuxdeploy-plugin-qt will look for all imported QML modules and include them. `$QT_INSTALL_QML` is prepended to this list internally.
67163
- `$QML_MODULES_PATHS`: extra directories containing imported QML files (normally doesn't need to be specified).
164+
165+
## Developer details
166+
### Standard paths
167+
Here are standard Qt lookup paths of appimage contents (same in Qt5 and Qt6):
168+
169+
```
170+
PrefixPath: /tmp/.mount_<random_id>/usr
171+
DocumentationPath: /tmp/.mount_<random_id>/usr/doc
172+
HeadersPath: /tmp/.mount_<random_id>/usr/include
173+
LibraryExecutablesPath: /tmp/.mount_<random_id>/usr/libexec
174+
BinariesPath: /tmp/.mount_<random_id>/usr/bin
175+
PluginsPath: /tmp/.mount_<random_id>/usr/plugins
176+
QmlImportsPath: /tmp/.mount_<random_id>/usr/qml
177+
ArchDataPath: /tmp/.mount_<random_id>/usr
178+
DataPath: /tmp/.mount_<random_id>/usr
179+
TranslationsPath: /tmp/.mount_<random_id>/usr/translations
180+
ExamplesPath: /tmp/.mount_<random_id>/usr/examples
181+
TestsPath: /tmp/.mount_<random_id>/usr/tests
182+
SettingsPath: /tmp/.mount_<random_id>/usr
183+
```

0 commit comments

Comments
 (0)