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

update-desktop-files as part of openSUSE/SUSE specific translation projects

Description of %suse_update_desktop_file in openSUSE Packaging Conventions

packaging mailing list deprecation discussion

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 or Comment.

Name, GenericName or Comment change, diverging from the upstream.

Addition of translations for Name, GenericName, Comment or Keywords that don't exist in the upstream.

Name, GenericName, Comment or Keywords translation change, diverging from the upstream.

Changes in Categories or introduction of new Categories, 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 or Keywords contain what the Desktop Entry Specification says? Note that .desktop file with Name equal to GenericName and/or Comment 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 of update-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:

suse-desktop-translations on GitHub

suse-desktop-translations in Weblate

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.

openSUSE:Update-desktop-files deprecation

Contents