Language support

[ahenket]

I noticed that SQF has language support. People love their own language. There're a couple of things that I was missing:

• You can mark sqf:description of sqf:title with a language, but you cannot add more than 1. I lean towards making sqf:description repeatable for a multi lingual fix, rather than sqf:title, so I can have proper sqf:p text associated. However: then I do not see the point of having @xml:lang on nodes under sqf:description.
• I also lean towards letting the sqf processor decide on fallback when the UI language of choice is not available, but by convention you could say the first available sqf:description is the default.

This would do it for my purposes:
<sqf:fix id="addHyphen">
<sqf:description xml:lang="en-US">
<sqf:title>Add Hyphen</sqf:title>
</sqf:description>
<sqf:description xml:lang="de-DE">
<sqf:title>Bindestrich hinzufügen</sqf:title>
</sqf:description>
<sqf:description xml:lang="nl-NL">
<sqf:title>Hyphen toevoegen</sqf:title>
</sqf:description>
<sqf:replace match="@Prefix" target="prefix" node-type="attribute">
<sch:value-of select="concat(.,'-')"/>
</sqf:replace>
</sqf:fix>

We deploy a solution that generates Schematron with localized asset/report texts. As far as we know Schematron itself only does 1 language per file hence either English, German or Dutch. In principle this means that we only need one sqf language at a time, but we always wished we did not have to generate multiple instances of the Schematron and with sqf it seems within reach through the descriptions.

[nkutsche]

Hi,
thank you for the feedback! You are absolutely right. I changed the schema to support multiple descriptions. I also started a Localization section in the spec, I want to describe this subject.
"As far as we know Schematron itself only does 1 language per file hence either English, German or Dutch."
Are you familiar with the localization concept in Schematron?
http://www.schematron-quickfix.com/escali_xsm/escali-ext_en.html#sqf:d110e783
As far as I know, there is no other implementation which support this. But it complies with the Schematron standard, so maybe you'll find in future more implementations for this.

[ahenket]

Hi and thanks for picking this up. We have not ventured into what diagnostics may bring us. I'll start some investigation on pros and cons. Thanks for the pointer.

[nkutsche]

This issue was subject of a concept session during the XMLPrague 2016. Read the full concept paper here.

The discussion was a result of the discussions of the issue #2. Following a summary of the discussed topics, conclusions and open issues:

Discussion

• The concept of The call-fix strucure is not user friendly #2 includes a localisation concept:
  • Multiple descriptions which have to be in different languages.
  • Concept for adding a description to an existing fix.
• There is no concept for referring to descriptions, which are stored in an external file (library).

Conclusions

There was no final concept for this issue, just a couple of proposals:

• Use Schematron localisation concept.
  • Add @diagnostic to sqf:title and sqf:p.
  • Remove the @xml:lang from the sqf:description.
  • Add @diagnostic to sqf:description with maybe multiple ids for localisation.
  • Multiple sqf:title with @xml:lang.
  • Only one sqf:description per sqf:fix element.
  • Main goal would be to have all sqf:title/sqf:p in one external document.
• Design an own referencing concept for descriptions.
  • Something like sqf:diagnostic, but there was no further discussion about that.
• Allow to specify global descriptions and refer them.
  • Allow sqf:description in sqf:fixes.
  • Add ref and id attribute to sqf:description.
  • An empty sqf:description element with a ref attribute refers to a global sqf:description element with an id attribute.

Open Issues

• The different proposals should be discussed.
• Maybe a localisation specialist should be called in.

[nkutsche]

Hi,

I had an idea about this open issue!

What if we allow the following:

<sqf:fixes>
	<sqf:fix>
		<sqf:description xml:lang="nl">
			<sqf:title>...</sqf:title>
			...
		</sqf:description>
		<sqf:description diagnostic="diagn_en_title diagn_en_p1 diagn_en_p2"/>
		<sqf:description diagnostic="diagn_de_title diagn_de_p1 diagn_de_p2"/>
		<!-- ... -->
	</sqf:fix>
</sqf:fixes>
<sch:diagnostics>
	<sch:diagnostic id="diagn_en_title" xml:lang="en">...</sch:diagnostic>
	<sch:diagnostic id="diagn_en_p1" xml:lang="en">...</sch:diagnostic>
	<sch:diagnostic id="diagn_en_p2" xml:lang="en">...</sch:diagnostic>
	
	<sch:diagnostic id="diagn_de_title" xml:lang="de">...</sch:diagnostic>
	<sch:diagnostic id="diagn_de_p1" xml:lang="de">...</sch:diagnostic>
	<sch:diagnostic id="diagn_de_p2" xml:lang="de">...</sch:diagnostic>
</sch:diagnostics>

The rules would be:

• You can use specific sqf:description with sqf:title and sqf:p or refer to sch:diagnostic elements using @diagnostic
• If you have multiple references to sch:diagnostic (from the same lang), the first referred diagnostic will be treated as title, the others as documentation paragraphs (sqf:p).
• If you mix references to different languages (which shouldn't be recommended), it will be treated as if they was referenced by separate sqf:description elements.
• It should be required, that sqf:description elements with a diagnostic attribute needs to be empty.
• If the sqf:description has an xml:lang and a diagnostic attribute, the value should correspond to the referred sch:diagnostic languages. I'm not sure, if this rule is necessary, but it could be useful for a better overview of the used description languages and a validation of my references. Alternatively, I would not permit the xml:lang attribute in combination with the diagnostic attribute.

I think this is a good compromise between the proposals we made last year.

Positives:

• It is using the Schematron localization concept (which also includes multiple diagnostic references).
• There would be just small changes needed in the existing structure.
• The localization by using sqf:call-fix works too (see issue The call-fix strucure is not user friendly #2).
• We avoid such non-intuitive structures like sqf:fixes/sqf:description for global descriptions or complete new structures

Negatives:

• The logic is maybe a bit complicate to understand, but only for developers who wants to use this diagnostics and have additional documentation paragraphs (sqf:p elements).

Please let me know, what you think about this proposal.

[octavianN]

Hi Nico,

It is an interesting proposal, but I think that if we want to use the Schematron localization concept also for SQF we need to allow only one sqf:description element. We can specify the diagnostics ids using the @diagnostic attribute on the sqf:description/sqf:title and sqf:description/sqf:p.

<sqf:fixes>
	<sqf:fix>
		<sqf:description>
			<sqf:title diagnostic="fix1_en_title fix1_de_title">The default message</sqf:title>
                       <sqf:p diagnostic="fix1_en_descr fix2_de_descr">The default description</sqf:p>
			...
		</sqf:description>
		<!-- ... -->
	</sqf:fix>
</sqf:fixes>
<sch:diagnostics>
	<sch:diagnostic id="fix1_en_title" xml:lang="en">...</sch:diagnostic>
	<sch:diagnostic id="fix1_en_descr" xml:lang="en">...</sch:diagnostic>
	
	<sch:diagnostic id="fix1_de_title" xml:lang="de">...</sch:diagnostic>
	<sch:diagnostic id="fix1_de_descr" xml:lang="de">...</sch:diagnostic>
</sch:diagnostics>

Then you can control the language of the messages displayed to the user in the same way as in Schematron.

Best Regards,
Octavian

[nkutsche]

Hi,

I just pushed changes in a new branch feature/1-language-support. Finally I could manage to realize the outcome of our discussions into the specification and the schema / sqf.sch. I just made some smaller modifications because then I can live with it better:

• I named the additional attribute not diagnostic but just generic ref
• The spec just says, that the reference to a sch:diagnostic element is the minimal implementation of the ref attribute. The implementations are free to support other types of references (@tofi86 for instance to Java property files)

Hope this is ok for all. Maybe you can give me your (positive ;-)) feedback so we can close this issue and publish the second draft finally!

[octavianN]

Hello,

We just released XML Editor version 20, and we added multilingual support for the SQF messages. If you want to provide an alternative message for a specific language, you can reference IDs or key values for the specific alternate text phrase. In Oxygen XML Editor, the alternate text phrase is defined in a sch:diagnostic element.

You can read more about this in our user manual: https://www.oxygenxml.com/doc/versions/20.0/ug-editor/topics/localizing-sqf-messages.html

Best Regards,
Octavian