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

Tweak language content to address remaining checklist issues #136

Merged
merged 6 commits into from
Dec 18, 2023
Merged

Tweak language content to address remaining checklist issues #136

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0da547f
Move language-related subsections into common i18n section (#125)
fsteeg Sep 12, 2023
d2a49fd
Tweak language content to address remaining checklist issues (#125)
fsteeg Sep 12, 2023
70eb13f
Make default text direction an explicit setting in the manifest (#136)
fsteeg Dec 12, 2023
d2ca1e6
Clarify requirements for language headers (#136)
fsteeg Dec 12, 2023
b400ac9
Add section to define the two types of language declaration (#136)
fsteeg Dec 12, 2023
bf8446d
Merge remote-tracking branch 'origin/master' into 125-language
fsteeg Dec 18, 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
62 changes: 35 additions & 27 deletions draft/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,11 @@
"publisher": "IETF",
"href": "https://www.rfc-editor.org/rfc/bcp/bcp47.txt"
},
"IANA Language Subtag Registry": {
"title": "IANA-maintained registry of language subtags",
"publisher": "IANA",
"href": "https://www.iana.org/assignments/language-subtag-registry"
},
}
};
</script>
Expand Down Expand Up @@ -459,17 +464,6 @@ <h3>Cross-Origin Access</h3>
enables older web-based clients to access the service from a different domain.
</p>
</section>
<section>
<h3>Language Selection</h3>
<p>
Following [[RFC9110]], services SHOULD use the <code>Accept-Language</code> header to let clients select the language in which user-facing text is returned.
They SHOULD use the <code>Content-Language</code> in their responses to expose the language each response is returned in.
</p>
<p>
Examples of user-facing text in service responses are: the name of the service and the name of property configuration fields in the manifest, the name and description of entities, types and properties,
the contents of the entity preview pages, and the documentation linked in the manifest.
</p>
</section>
<section>
<h3>Error Handling and Rate-limiting</h3>
<p>
Expand Down Expand Up @@ -916,6 +910,36 @@ <h3>Data Extension Responses</h3>
</p>
</section>
</section>
<section>
<h2>Internationalization Considerations</h2>
<section>
<h3>Language of the intended audience</h3>
<p>
Following [[RFC9110]], services SHOULD support the <code>Accept-Language</code> header to let clients specify the preferred language in which user-facing text is returned. The language(s) requested by clients MUST be well-formed [[BCP 47]] language tags.
Services SHOULD use the <code>Content-Language</code> header in their responses to expose the language(s) of the intended audience(s) of each response. Services MUST return valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] tags.
</p>
<p>
Examples of user-facing text in service responses are: the name of the service and the name of property configuration fields in the manifest, the name and description of entities, types and properties,
the contents of the entity preview pages, and the documentation linked in the manifest.
</p>
</section>
<section>
<h3>Text-processing language</h3>

<p>All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit <a href="https://www.w3.org/International/questions/qa-text-processing-vs-metadata">
text-processing language</a> in a <code>lang</code> field. The <code>lang</code> value MUST be a single valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] language tag. This text-processing language applies to the natural language fields of the object: <code>name</code>, <code>description</code>,
<code>query</code> (for <a>reconciliation queries</a>), <code>v</code> and <code>str</code> (for <a>property values</a>). Nested objects inherit the text-processing language of their parent, and can override it by setting their own <code>lang</code> value
(see example below). Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.</p>

<p>In the following example, we first set the text-processing language for a reconciliation query to <code>en</code>, which is inherited by the first property, and overridden in the second property with <code>zh-Hant</code>:</p>

<p>
<pre data-include="examples/reconciliation-query-batch/valid/text-processing-language.json" class="example json"></pre>
</p>

<p>If no explicit text-processing language is given, the first <a href="#language-of-the-intended-audience">language of the intended audience</a> returned by the service is considered the default text-processing language.</p>
</section>
</section>
<section>
<h2>Accessibility Considerations</h2>
<p>
Expand Down Expand Up @@ -945,22 +969,6 @@ <h3>Content semantics</h3>
be modified by third-party tools to enhance accessibility.
</p>
</section>
<section>
<h3>Text-processing language</h3>

<p>All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit <a href="https://www.w3.org/International/questions/qa-text-processing-vs-metadata">
text-processing languge</a> in a <code>lang</code> field. The <code>lang</code> value MUST be a single well-formed [[BCP 47]] language tag. This text-processing languge applies to the natural language fields of the object: <code>name</code>, <code>description</code>,
<code>query</code> (for <a>reconciliation queries</a>), <code>v</code> and <code>str</code> (for <a>property values</a>). Nested objects inherit the text-processing language of their parent, and can override it by setting their own <code>lang</code> value
(see example below). Client and service implementors SHOULD consider the text-processing languge to ensure correct processing of natural language content.</p>

<p>In the following example, we first set the text-processing language for a reconciliation query to <code>en</code>, which is inherited by the first property, and overridden in the second property with <code>zh-Hant</code>:</p>

<p>
<pre data-include="examples/reconciliation-query-batch/valid/text-processing-language.json" class="example json"></pre>
</p>

<p>If no explicit text-processing language is given, the metadata language (the language of the intended audience) provided first (see <a href="#service-definition">service definition</a>) is considered the default text-processing language.</p>
</section>
</section>
<section>
<h2>Security Considerations</h2>
Expand Down