New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Language support #1

Open
ahenket opened this Issue May 15, 2015 · 7 comments

Comments

Projects
None yet
3 participants
@ahenket

ahenket commented May 15, 2015

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

This comment has been minimized.

Show comment
Hide comment
@nkutsche

nkutsche May 16, 2015

Contributor

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.

Contributor

nkutsche commented May 16, 2015

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

This comment has been minimized.

Show comment
Hide comment
@ahenket

ahenket May 19, 2015

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.

ahenket commented May 19, 2015

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 comment has been minimized.

Show comment
Hide comment
@nkutsche

nkutsche Feb 22, 2016

Contributor

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 #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.
Contributor

nkutsche commented Feb 22, 2016

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 #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

This comment has been minimized.

Show comment
Hide comment
@nkutsche

nkutsche Jan 17, 2017

Contributor

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 #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.

Contributor

nkutsche commented Jan 17, 2017

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 #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

This comment has been minimized.

Show comment
Hide comment
@octavianN

octavianN Jan 19, 2017

Contributor

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

Contributor

octavianN commented Jan 19, 2017

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

This comment has been minimized.

Show comment
Hide comment
@nkutsche

nkutsche Jan 15, 2018

Contributor

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!

Contributor

nkutsche commented Jan 15, 2018

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

This comment has been minimized.

Show comment
Hide comment
@octavianN

octavianN Mar 19, 2018

Contributor

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

Contributor

octavianN commented Mar 19, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment