Improve <translation/> description in spec

[kparal]

After the discussion in hughsie/appstream-glib#302, I have a few suggestions how to improve <translation/> description in AppStream spec:
https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#sect-Metadata-GenericComponent

1. It helps a lot if the purpose of this tag is explained even to non-programmer people (like packagers). I suggest changing this sentence:

It may be used by the AppStream distro metadata generator to determine the translation status of the respective software.

to something like this:

It may be used by the AppStream distro metadata generator to determine the translation status of the respective software (e.g. which languages the software is translated into and how complete the translations are).

2. Similarly to 1), I didn't understand the term "translation domain" and I didn't manage to find useful help online. In the end I realized it's the name of the *.mo file (for gettext) and then it's clear. It would be helpful it that could be explained better somehow (for all translation systems), but I don't know how.

3. @hughsie said appstream-glib now supports .pak and .xpi translation files. I'm not sure about your reference implementation, but is it something that should be incorporated in the spec as well?

4. It is unclear that <translations/> (an empty tag) is valid and what exactly it means. It can mean "this software is not translated" or it can mean "the translation status can't be determined by our tooling". (Now that appstream-glib made this tag mandatory in default validation pass, this is a question that will be asked by every packager of either proprietary software or software using unsupported translation systems). It would be good to clarify this, and ideally support both meanings in some way.

Thanks for consideration.

[ximion]

To 1): PR to change the text is very welcome :-)

To 2): The term "translation domain" is pretty common and should be well known to people using Gettext. I would expect these people to write the initial metainfo file as well, packagers should usually not need to know about this. But if the wording could be made more clear, patches are welcome there as well.

To 3): I rarely include stuff in the spec which is only supported by one implementation. The problem with translations made with other systems is that unlike Gettext those usually have no default paths to search for translations in, so hunting them down is really hard. So far we haven't found proper solutions for this issue.

To 4): I am quite certain that appstreamcli validate will currently see an empty translation tag as a bug and fail validation, as its meaning is undefined. If it was defined, its meaning would be "this software is untranslated" as that's what empty AppStream tags generally mean in other places (that and "assume default values").

[kparal]

To 1): PR to change the text is very welcome :-)

OK, please see #236.

To 4): I am quite certain that appstreamcli validate will currently see an empty translation tag as a bug and fail validation, as its meaning is undefined. If it was defined, its meaning would be "this software is untranslated" as that's what empty AppStream tags generally mean in other places (that and "assume default values").

You're correct:

$ appstreamcli validate org.freefilesync.FreeFileSync.appdata.xml
W - org.freefilesync.FreeFileSync.appdata.xml:org.freefilesync.FreeFileSync.desktop:77
    Found empty 'translation' tag.

E - org.freefilesync.FreeFileSync.appdata.xml:org.freefilesync.FreeFileSync.desktop:77
    'translation' tag has no 'type' property: 

Validation failed: errors: 1, warnings: 1

In that case I'll ask @hughsie to reconsider this tag being mandatory for appstream-glib, because in that case I'm unable to write an appstream file that would validate in both implementation (for software that's not using any of supported translation systems). The spec should be adjusted first, so that implementations can behave the same way.

[hughsie]

Found empty 'translation' tag.

I think this is bogus. In XML an empty tag is "we're informing you there is no value here" which is distinct for the "we don't know what this value is".

[ximion]

@hughsie I see it more as "the user copied a template from somewhere and forgot to enter a value". Unless a zero-value tag is explicitly allowed by the spec, appstreamcli will treat it as a warning, as the user may simply have forgotten to fill in a value.

[kparal]

I think this ticket is basically resolved now.

[hadess]

I still don't understand what I'm supposed to put in my appdata for software which isn't translated (or doesn't use a common translation method), like a few of the pieces of software I maintain in Flathub.

The spec doesn't mention this, and some tools don't treat it as optional.