openSUSE:Update-desktop-files deprecation
Introduction
In 2003, the upstream desktop files translation had a bad quality, as well as desktop tree menu. To prevent ugly and half translated desktop menu, SuSE Linux (actually Novell Linux Desktop 9) introduced the %suse_update_desktop_file
macro. It was even mandatory many years ago.
Few year later, an opaque process hidden to the package maintainers was invented, and all desktop files are sent to translators. It uses brp scripts, and it is completely opaque to the package maintainers and changes are invisible to them. These SUSE-specific translations are preferred over the upstream ones.
Additionally, the whole concept of update-desktop-files
completely contradicts our policy "Upstream first".
New version of update-desktop-files
is going to Factory in 2024-11. For the first time it makes possible to upstream SUSE desktop translations done in the last 20 years. The upstreaming requires coordination with package maintainers and the upstream. Package maintainers need to check build logs for the instructions and decide how to upstream the desktop translations.
There are more reasons why update-desktop-files
should be dropped, and desktop translations should be moved to the upstream:
- It often duplicates upstream translation effort, wasting a human work, both community translators and contracted ones.
- Most of these translations are ~20 years old, and they were never reviewed, so it is possible that they are worse than the upstream ones. In the last 20 years it did not provide any way to upstream the changes and translations. The upstream translations got another 20 years of development. Also Desktop Categories specification was updated, and the upstream specification now covers all aspects of former
X-SuSE-*
Categories extensions.
- As a result, the SUSE desktop menu experience differs from other vendors. Applications have a different name, different translations, different placement in the structured menu etc.
- Upstream translations have a wider impact.
- Package maintainers have only a limited control over the contents visible to users. It is imported during the runtime, and the visible contents could be different from the contents in the package.
- update-desktop-files is a complicated tool. It attempts to fix deprecated and obsolete stuff in the desktop files without even informing the developer that something was wrong and something was modified.
- It uses a very complicated toolchain that requires access to SUSE intranet and access to OpenQA VPN. The complete toolchain setup was never published, so it has even problems with Open Source ideas.
- It mixes SUSE-unique translations with translations that just duplicate the upstream translation effort. As a result it significantly increases number of strings to translate and decreases the quality of the translation.
The project in numbers
Use of %suse_update_desktop_file
: 1149 packages
Use of %suse_update_desktop_file
without any changes involved: 54 packages
Use of update-desktop-files
without actually using the macro: 167 packages
Use of %suse_update_desktop_file
translations: 928 packages (1127 desktop files)
Use of opaque translation process not visible in the spec file: 5747 packages (4811 unique)
Total number of translated strings (in all languages): 380433
More about update-desktop-file
Deprecation plan
update-desktop-files
is different from other translation projects. As it modifies translations and desktop files that come from the upstream, changes done by that project have to be moved to the upstream. That is why it cannot be easily dropped.
Here is the proposed obsoleting plan:
- November 2024:
update-desktop-files
in Factory
- Early 2025: Packages using the opaque process get a chance to upstream the openSUSE/SUSE specfic changes.
- March 2025: Proposed changes are reviewed by package maintainers and sent to the upstream.
- End of 2025: Proposed changes are reviewed by the upstream and either upstreamed or dropped. Package maintainers import these changes back to Factory with the next version update.
- Early 2026: Packages that did not get an upstream update are being patched instead of use of
update-desktop-files
- During 2026: Use of
update-desktop-files
generates an error and the package is being dropped.
Upstreaming
A deprecation process and upstreaming update-desktop-files translations was started in 2024. A goal of this effort is a complete upstreaming of all SUSE specific changes, and then dropping of custom translations.
What can include SUSE specific changes
- Addition of
GenericName
orComment
.
Name
,GenericName
orComment
change, diverging from the upstream.
- Addition of translations for
Name
,GenericName
,Comment
orKeywords
that don't exist in the upstream.
Name
,GenericName
,Comment
orKeywords
translation change, diverging from the upstream.
- Changes in
Categories
or introduction of newCategories
, effectively changing a layout of the structured menu.
Considerations
It makes sense to review all these changes, think about them and send them to the upstream.
In case of changes diverging from the upstream, please consider that SUSE specific changes and diverging translations were probably made ~20 years ago, and they have a much smaller community of testers.
Review resources
You can use these resources to make the review:
- Does
Name
,GenericName
,Comment
orKeywords
contain what the Desktop Entry Specification says? Note that.desktop
file withName
equal toGenericName
and/orComment
is not considered as a good practice.
- Do the new
Categories
match better? Or does the change fix the incorrect use? Each primary category should list at least one secondary category. And each secondary category used requires a corresponding primary category. See Registered Categories in Desktop Menu Specification
- Are the upstream translations old? If yes, it makes sense to overwrite them by SUSE specific ones. If not, it makes sense to prefer the upstream, and use SUSE translation only for missing strings.
- Verify that the desktop file intended for upstreaming does not contain any SUSE specific stuff (e. g.
X-SUSE-*
).
- The empty line changes are purely cosmetic changes and they can be ignored.
- When fixing the desktop file, please fix warnings from the desktop-file-validate, as they are presented by the rpmlint check. (If there are any.)
Proposed patches generated by update-desktop-files
To simplify the upstreaming, please check suse_update_desktop_file
in the top of the build directory or the file update-desktop-files.tar.gz
in the build results:
https://{obs_instance}/build/{project}/{repository}/{arch}/{package}/update-desktop-files.tar.gz
or
osc getbinaries {repository} {arch} update-desktop-files.tar.gz
Then unpack it in the source directory.
You can find following files there:
{desktop name}-downstream-directly-translated.diff
: If the application has no translation toolkit, review and apply it and send to the upstream.
{desktop name}-downstream-in-translated.diff
: If the application has a translation toolkit, review and apply it and send to the upstream and merge translations from the po files. This patch is intended for intltool and similar tools that translate keys starting by_
.
{desktop name}-downstream-no-translation.desktop
: This file contains all modifications done by %suse_update_desktop_file except translations.
{desktop name}-downstream-no-translation.desktop.in
: This file contains all modifications done by %suse_update_desktop_file except translations. It is converted to the format accepted by intltool.
{desktop name}-downstream-translated.desktop
: This file contains all modifications done by %suse_update_desktop_file including translations.
{desktop name}-upstream.desktop
: The original desktop file provided by the upstream.
{desktop name}-upstream.desktop.in
: The original desktop file provided by the upstream. It is converted to the format accepted by intltool.
How to upstream
If the package belongs to YaST
Do nothing for now. You are the upstream. The replacement does not exist yet. For more see Bug 1232409 - desktop translations: replace deprecated update-desktop-files by another tool.
If the application has a translation toolkit
- Review
{desktop name}-downstream-in-translated.diff
and apply it.
- Pick the po directory and merge it to the upstream po files.
- Verify that the desktop file does not contain any SUSE specific stuff (e. g.
X-SUSE-*
).
How to merge translation changes into the upstream po files
Suppose that the correct translation directory is po
cd update-desktop-files/{desktop name}/po for PO in *.po ; do if test -f ../../../po/$PO ; then msgcat --use-first $PO ../../../po/$PO -o ../../../po/$PO.new mv ../../../po/$PO.new ../../../po/$PO else cp -a $PO ../../../po/$PO fi done
This command prefers the SUSE translations over the upstream ones. If you want to prefer existing upstream translations over the SUSE specific ones, swap arguments of msgcat
:
msgcat --use-first ../../../po/$PO $PO -o ../../../po/$PO.new
Notes:
- It is possible that the desktop file is placed in a subdirectory, and it could have a suffix
.in.in
.
- The project can have multiple translation domains (and directories) and the correct translations directory could be different than po.
- If there are more
%update_desktop_files
, you need to repeat these steps for all subdirectories ofupdate-desktop-files
.
- You can safely ignore warnings about not matching plurals. Desktop files never use plural forms.
- It is recommended to update the po files using the latest pot file. The way to do it can be package dependent, but the common way to do it is:
make cd po make update-po
If the package has an upstream translation server
Some packages use a dedicated translation server for translations (e. g. Weblate). Then the process could require use of this server and submit the po files there. Some of these tools allow to submit partial po files (e. g. those generated by the tool), some of them may require complete po files. If the frontend supports review, it makes sense to submit SUSE translations for review.
You can also contact the developers and ask for the help.
If the application has no translation toolkit
- Review
{desktop name}-downstream-directly-translated.diff
, apply it and send to the upstream.
- Verify that the desktop file does not contain any SUSE specific stuff (e. g.
X-SUSE-*
).
Sending or applying patches
When your work is done, please send your changes to the upstream for review. When the upstream includes them (or consciously decides to not include), please upgrade and remove
BuildRequires: update-desktop-files
and
%suse_update_desktop_file {arguments}
Now your package finally conforms to the Upstream First policy.
If the upstream project is dead, please apply the generic changes as a patch. It makes the sources more readable. And consider adding the desktop file to the translate-suse-desktop
project. Read further.
Desktop file exists only in the spec file
In that case, your desktop file is probably SUSE specific and you do not need to upstream anything. You just need to become the upstream. Just migrate from heavy weight update-desktop-files (containing strings duplicating the upstream translation effort with unique strings) to a simple translate-suse-desktop
tool.
For more see translate-suse-desktop documentation.
During the next run of string collection, your strings will be included to:
You don't need to care about the translation migration from desktop-file-translations. The toolchain will do it automatically for you. If you want to speed up the process, please inform the translate-suse-desktop
maintainer.
Prepare the desktop file for translation with translate-suse-desktop
(basically intltool
one liner plus strings collection over all packages):
sed "/\(Name\|GenericName\|Comment\|Keywords\)\ [/d;s@^Name=@_Name=@;s@^GenericName=@_GenericName=@;s@^Comment=@_Comment=@;s@^Keywords=@_Keywords=@" <{desktop name}.desktop >{desktop name}.desktop.in
(intltool-prepare
does the same job.)
patch <{desktop name}-downstream-in-translated.diff
For convenience, move Categories from the top of the desktop file to the lower part (below Exec, Icon etc.).
Then modify the spec file: in preamble, change
BuildRequires: update-desktop-files
to
BuildRequires: translate-suse-desktop
and
Source{number}: {desktop name}.desktop
to
Source{number}: {desktop name}.desktop.in
In %prep
, copy Source{number}
to the build directory
cp %{SOURCE{NUMBER}} .
In %build
, add:
%translate_suse_desktop {desktop name}.desktop
And in %install
, change
%suse_update_desktop_file {arguments}
to
install -D -m 0644 {desktop name}.desktop %{buildroot}${DESKTOP_PATH#$RPM_BUILD_ROOT}{desktop name}.desktop
Then call:
osc add {desktop name}.desktop.in osc rm {desktop name}.desktop
Trick to backport translations to older openSUSE products
in preamble, add
Source{another_number}: {desktop name}.desktop.in
in addition to the existing:
Source{number}: {desktop name}.desktop
but add comment:
# Ready made desktop file for products that don't support %%translate_suse_desktop. # You can be prompted for the update during the Factory build. Source{number}: {desktop name}.desktop
In %prep
, do
%if 0%{?suse_version} > 1560 cp %{SOURCE{another_number}} %{desktop_file_name}.desktop.in.in %else cp %{SOURCE{number}} %{desktop_file_name}.desktop %endif
In %build
, add (preferably as a first action):
%if 0%{?suse_version} > 1560 %translate_suse_desktop %{desktop_file_name}.desktop if ! diff {desktop name}.desktop %{SOURCE{number}} ; then cat <<EOF A new version of desktop file exists. Please update {desktop name}.desktop rpm source from $PWD to get translations to older products. EOF exit 1 fi %endif
This approach has a downside: Whenever translate-suse-desktop
brings a new translation for that desktop file, Factory build fails. On the other hand, the failure fix could be easily automated.
Another approach is possible as well: E. g. put the fully translated desktop file to OTHER
dir, and then pull them by osc getbinaries
as part of pre_checkin.sh
.
Contact
In case of problems, please contact Stanislav Brabec.