Skip to content
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.

Sign up for GitHub

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

Include input & option descriptions as data in registry #533

Merged
merged 5 commits into from
Dec 11, 2023
Merged

Include input & option descriptions as data in registry #533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b9cbbc6
Actually include input & option descriptions as data in registry, not…
eemeli Nov 27, 2023
92c29b2
Use CLDR as currency code reference
eemeli Dec 8, 2023
682a290
Add xml:lang attributes to <registry>, <input> and <option>
eemeli Dec 8, 2023
0024507
Wrap all descriptions in <description> elements
eemeli Dec 8, 2023
2679b6d
Merge branch 'main' into option-descriptions
eemeli Dec 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions spec/registry.dtd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,17 @@
<!ELEMENT registry (function|validationRule)*>
<!ATTLIST registry
xml:lang NMTOKEN #IMPLIED
>
Comment on lines +2 to +4
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added xml:lang as an optional attribute on the top-level <registry>, as well as directly on <input> and <option>, to indicate the language of the included descriptions.

Should this be required, though? Or are there use cases where a <registry> could be e.g. embedded in another XML document, where the locale is defined somewhere further up the tree?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should do this differently. Literally in the next tab of the browser I have a PR open on string-meta with best practices. See also this article.

I think we'd be best off here by putting the natural language string descriptions into sub-elements description which are allowed to vary by xml:lang. Setting xml:lang="en" at the registry element level would allow us to have <description> without xml:lang attributes throughout.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. Many <desciption> now.


<!ELEMENT function (description,(formatSignature|matchSignature|alias)+)>
<!ELEMENT function (description+,(formatSignature|matchSignature|alias)+)>
<!ATTLIST function
name NMTOKEN #REQUIRED
>

<!ELEMENT description (#PCDATA)>
<!ATTLIST description
xml:lang NMTOKEN #IMPLIED
>

<!ELEMENT validationRule EMPTY>
<!ATTLIST validationRule
Expand All @@ -20,14 +26,14 @@

<!ELEMENT matchSignature (input?,option*,match*,override*)>

<!ELEMENT input EMPTY>
<!ELEMENT input (description*)>
<!ATTLIST input
values NMTOKENS #IMPLIED
validationRule IDREF #IMPLIED
readonly (true|false) "false"
>

<!ELEMENT option EMPTY>
<!ELEMENT option (description*)>
<!ATTLIST option
name NMTOKEN #REQUIRED
values NMTOKENS #IMPLIED
Expand Down
11 changes: 8 additions & 3 deletions spec/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ The registry contains descriptions of function signatures.

The main building block of the registry is the `<function>` element.
It represents an implementation of a custom function available to translation at runtime.
A function defines a human-readable _description_ of its behavior
A function defines a human-readable `<description>` of its behavior
and one or more machine-readable _signatures_ of how to call it.
Named `<validationRule>` elements can optionally define regex validation rules for
literals, option values, and variant keys.
Expand Down Expand Up @@ -74,6 +74,11 @@ which provide shorthands for commonly used option baskets.
An _alias name_ may be used equivalently to a _function name_ in messages.
Its `<setOption>` values are always set, and may not be overridden in message annotations.

If a `<function>`, `<input>` or `<option>` includes multiple `<description>` elements,
each SHOULD have a different `xml:lang` attribute value.
This allows for the descriptions of these elements to be themselves localized
according to the preferred locale of the message authors and editors.

## Example

The following `registry.xml` is an example of a registry file
Expand All @@ -84,7 +89,7 @@ For the sake of brevity, only `locales="en"` is considered.
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE registry SYSTEM "./registry.dtd">

<registry>
<registry xml:lang="en">
<function name="platform">
<description>Match the current OS.</description>
<matchSignature>
Expand Down Expand Up @@ -165,7 +170,7 @@ A localization engineer can then extend the registry by defining the following `
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE registry SYSTEM "./registry.dtd">

<registry>
<registry xml:lang="en">
<function name="noun">
<description>Handle the grammar of a noun.</description>
<formatSignature>
Expand Down
Loading