Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "COSMOS Design 238000"
(→Purpose) |
(→Purpose) |
||
| Line 74: | Line 74: | ||
The locid attribute is introduced in SML 1.1 to provide capability to retrieve localized strings for text elements within an SML document. The specification provided an example for using the locid in schematrons to provide localized error messages. This enhancement implements the support of locid in schematrons for the SML validator. | The locid attribute is introduced in SML 1.1 to provide capability to retrieve localized strings for text elements within an SML document. The specification provided an example for using the locid in schematrons to provide localized error messages. This enhancement implements the support of locid in schematrons for the SML validator. | ||
| + | =Requirements= | ||
| + | |||
| + | The locid attribute is for providing information necessary to retrieve the localized text. The specification is not technology dependent. Our implementation will use the Java resource bundle to retrieve localized strings. | ||
| + | |||
| + | The enhancement implements the example provided in Appendix F of the SML specification: http://www.w3.org/TR/sml/#LocalizationSample | ||
| + | |||
| + | |||
| + | =Design= | ||
| + | |||
| + | == Locating the resource bundle == | ||
| + | The sml:locid attribute will have two parts: a prefix and a key to a string.<br> | ||
| + | e.g. sml:locid="lang:StudentIDErrorMsg" | ||
| + | |||
| + | There is a namesapce URI associated with the prefix, defined in one of the parent elements. The format of the URI and how to use the URI to locate the translated resource is out of the scope of the SML specification. So it is an application specific design decision on how to use the URI to locate the translated resources and retrive the appropriate value. In this implementation, we require the URI to be formatted in the following structure: | ||
| + | |||
| + | sml:<bundle name>[:<locale>] | ||
| + | * the first segment "sml" is the scheme of the URI. It is a dummy value to make the URI a well formed absolute URI. | ||
| + | * <bundle name> is the fully qualified name of a Java resource bundle | ||
| + | * <locale> is the intended locale of the message. It is an optional field. | ||
| + | |||
| + | Notes: | ||
| + | * URI used in namespaces have to be in absolution form. Relative URI not allowed. | ||
| + | * The URI format above complies with the URI syntax defined here: http://www.ietf.org/rfc/rfc2396.txt | ||
| + | |||
| + | Examples: | ||
| + | *sml:org.ecllipse.cosmos.rm.internal.messages.Message | ||
| + | *sml:org.ecllipse.cosmos.rm.internal.messages.Message:fr | ||
| + | *sml:org.ecllipse.cosmos.rm.internal.messages.Message:pt_BR | ||
| + | |||
| + | == String substitution == | ||
| + | Section 7.1 and Appendix F of the SML specification discusses the use case of string substitution in localized string. However, the sml:locid attribute does not provide information on string substitution. The SML specification only suggest ways to do string substitution but it is not a normative part of the specifiation. | ||
| + | |||
| + | The example in Appendix F of the specification embeds the schematron "value-of" element in the message to do string substitution. This implementation will follow the example closely. | ||
| + | |||
| + | |||
| + | == Algorithm == | ||
| + | The enhancement will change ElementSchematronCacheBuilder data builder to replace text elements with a translated version before passing the schematron to the XSLT transformer. | ||
| + | |||
| + | *In StartElement method of ElementSchematronCacheBuilder.java, check for the presence of the sml:locid attribute. | ||
| + | * If the sml:locid attribute is present, attempt to retrieve the value indicated in the locid attribute from a resource bundle. | ||
| + | ** get prefix and message key from the attribute value | ||
| + | ** look up the namespace associated with the prefix (some new data structures are required to do this. SAX parsers do not provide prefix lookup.) | ||
| + | ** parse the namespace URI for bundle name and the optional locale value | ||
| + | ** load the resource bundle and retrieve string by message key | ||
| + | * If the retrieval is not successful, the sml:locid value will be ignored. | ||
| + | * If the retrieval is successful, then | ||
| + | ** append the string from resource bundle to the rule fragment, right after the openning element tag of the current element. | ||
| + | ** set a flag to suppress the text element and <sch:value-of> elements from being appended to the rule fragment. | ||
| + | ** unset the flag in the EndElement event of the element with the sml:locid attribute defined. | ||
== Open Issues/Questions == | == Open Issues/Questions == | ||
Revision as of 11:57, 22 July 2008
Contents
Support locid attribute in SML Validation
Change History
| Name: | Date: | Revised Sections: |
|---|---|---|
| David Whiteman | 06/24/2008 |
|
Workload Estimation
| Process | Sizing | Names of people doing the work |
|---|---|---|
| Design | .5 | David Whiteman |
| Code | 2* | David Whiteman |
| Test | 1 | David Whiteman |
| Documentation | 0 | |
| Build and infrastructure | 0 | |
| Code review, etc.* | 0 | |
| TOTAL | 3.5 |
- -- sizing assumes current RM team member
Terminologies/Acronyms
The terminologies/acronyms below are commonly used throughout this document.
| Term | Definition |
|---|---|
| SML | Service Modeling Language |
| SML-IF | Service Modeling Language - Interchange Format |
Purpose
This document is associated with bugzilla 238000.
We need to implement the optional sml:locid attibute in our validator.
The locid attribute is introduced in SML 1.1 to provide capability to retrieve localized strings for text elements within an SML document. The specification provided an example for using the locid in schematrons to provide localized error messages. This enhancement implements the support of locid in schematrons for the SML validator.
Requirements
The locid attribute is for providing information necessary to retrieve the localized text. The specification is not technology dependent. Our implementation will use the Java resource bundle to retrieve localized strings.
The enhancement implements the example provided in Appendix F of the SML specification: http://www.w3.org/TR/sml/#LocalizationSample
Design
Locating the resource bundle
The sml:locid attribute will have two parts: a prefix and a key to a string.
e.g. sml:locid="lang:StudentIDErrorMsg"
There is a namesapce URI associated with the prefix, defined in one of the parent elements. The format of the URI and how to use the URI to locate the translated resource is out of the scope of the SML specification. So it is an application specific design decision on how to use the URI to locate the translated resources and retrive the appropriate value. In this implementation, we require the URI to be formatted in the following structure:
sml:<bundle name>[:<locale>]
- the first segment "sml" is the scheme of the URI. It is a dummy value to make the URI a well formed absolute URI.
- <bundle name> is the fully qualified name of a Java resource bundle
- <locale> is the intended locale of the message. It is an optional field.
Notes:
- URI used in namespaces have to be in absolution form. Relative URI not allowed.
- The URI format above complies with the URI syntax defined here: http://www.ietf.org/rfc/rfc2396.txt
Examples:
- sml:org.ecllipse.cosmos.rm.internal.messages.Message
- sml:org.ecllipse.cosmos.rm.internal.messages.Message:fr
- sml:org.ecllipse.cosmos.rm.internal.messages.Message:pt_BR
String substitution
Section 7.1 and Appendix F of the SML specification discusses the use case of string substitution in localized string. However, the sml:locid attribute does not provide information on string substitution. The SML specification only suggest ways to do string substitution but it is not a normative part of the specifiation.
The example in Appendix F of the specification embeds the schematron "value-of" element in the message to do string substitution. This implementation will follow the example closely.
Algorithm
The enhancement will change ElementSchematronCacheBuilder data builder to replace text elements with a translated version before passing the schematron to the XSLT transformer.
- In StartElement method of ElementSchematronCacheBuilder.java, check for the presence of the sml:locid attribute.
- If the sml:locid attribute is present, attempt to retrieve the value indicated in the locid attribute from a resource bundle.
- get prefix and message key from the attribute value
- look up the namespace associated with the prefix (some new data structures are required to do this. SAX parsers do not provide prefix lookup.)
- parse the namespace URI for bundle name and the optional locale value
- load the resource bundle and retrieve string by message key
- If the retrieval is not successful, the sml:locid value will be ignored.
- If the retrieval is successful, then
- append the string from resource bundle to the rule fragment, right after the openning element tag of the current element.
- set a flag to suppress the text element and <sch:value-of> elements from being appended to the rule fragment.
- unset the flag in the EndElement event of the element with the sml:locid attribute defined.
Open Issues/Questions
All reviewer feedback should go in the Talk page for 238000.