From 0da547f3b5204181425f72b3fd64bb86b9d39af4 Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Tue, 12 Sep 2023 14:39:28 +0200 Subject: [PATCH 1/5] Move language-related subsections into common i18n section (#125) --- draft/index.html | 57 +++++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/draft/index.html b/draft/index.html index fbdba57..a643380 100644 --- a/draft/index.html +++ b/draft/index.html @@ -459,17 +459,6 @@

Cross-Origin Access

enables older web-based clients to access the service from a different domain.

-
-

Language Selection

-

- Following [[RFC9110]], services SHOULD use the Accept-Language header to let clients select the language in which user-facing text is returned. - They SHOULD use the Content-Language in their responses to expose the language each response is returned in. -

-

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

-

Error Handling and Rate-limiting

@@ -916,6 +905,36 @@

Data Extension Responses

+
+

Internationalization Considerations

+
+

Language Selection

+

+ Following [[RFC9110]], services SHOULD use the Accept-Language header to let clients select the language in which user-facing text is returned. + They SHOULD use the Content-Language in their responses to expose the language each response is returned in. +

+

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

+
+
+

Text-processing language

+ +

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

+ +

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

+ +

+ 


+        

+
+        
If no explicit text-processing language is given, the metadata language (the language of the intended audience) provided first (see service definition) is considered the default text-processing language.

+      

+    

     

       
Accessibility Considerations

       

@@ -945,22 +964,6 @@ 
Content semantics

           be modified by third-party tools to enhance accessibility.
         

       

-      

-        
Text-processing language

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

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

-
-        

-          

-        

-
-        
If no explicit text-processing language is given, the metadata language (the language of the intended audience) provided first (see service definition) is considered the default text-processing language.

-      

     
     

       
Security Considerations


From d2a49fd14c82bb17fcc2256b9e85620a0807d3bd Mon Sep 17 00:00:00 2001
From: Fabian Steeg 
Date: Tue, 12 Sep 2023 16:09:59 +0200
Subject: [PATCH 2/5] Tweak language content to address remaining checklist
 issues (#125)

In particular on valid / well-formed BCP 47 tags and IANA registry
---
 draft/index.html | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/draft/index.html b/draft/index.html
index a643380..e0e3fea 100644
--- a/draft/index.html
+++ b/draft/index.html
@@ -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"
+          },
         }
       };
     
@@ -908,10 +913,10 @@ 
Data Extension Responses

     

       
Internationalization Considerations

       

-        
Language Selection

+        
Language of the intended audience

         

-           Following [[RFC9110]], services SHOULD use the Accept-Language header to let clients select the language in which user-facing text is returned.
-           They SHOULD use the Content-Language in their responses to expose the language each response is returned in.
+           Following [[RFC9110]], services SHOULD support the Accept-Language 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 Content-Language 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.
         

         

           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,
@@ -922,9 +927,9 @@ 
Language Selection

         
Text-processing language

 
         
All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit 
-        text-processing languge in a lang field. The lang value MUST be a single well-formed [[BCP 47]] language tag. This text-processing languge applies to the natural language fields of the object: name, description,
+        text-processing language in a lang field. The lang 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: name, description,
         query (for reconciliation queries), v and str (for property values). Nested objects inherit the text-processing language of their parent, and can override it by setting their own lang value
-        (see example below). Client and service implementors SHOULD consider the text-processing languge to ensure correct processing of natural language content.

+        (see example below). Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.

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

 
@@ -932,7 +937,7 @@ 
Text-processing language

           

         

 
-        
If no explicit text-processing language is given, the metadata language (the language of the intended audience) provided first (see service definition) is considered the default text-processing language.

+        
If no explicit text-processing language is given, the first language of the intended audience returned by the service is considered the default text-processing language.

       

     

     


From 70eb13f272736d0d737fa56365f3559793a98e60 Mon Sep 17 00:00:00 2001
From: Fabian Steeg 
Date: Tue, 12 Dec 2023 11:13:49 +0100
Subject: [PATCH 3/5] Make default text direction an explicit setting in the
 manifest (#136)

Don't use the first language of the intended audience; see discussion at:

https://github.com/reconciliation-api/specs/pull/136#issuecomment-1719335631
---
 draft/index.html | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/draft/index.html b/draft/index.html
index e0e3fea..f12b16a 100644
--- a/draft/index.html
+++ b/draft/index.html
@@ -403,6 +403,8 @@ 
Service Manifest

           
The maximum number of reconciliation queries in a single reconciliation query batch.  The service MAY respond to batches larger than this number with a 413 HTTP error status code [[RFC7231]]

           
authentication

           
An security scheme, supplied if the service supports authentication.

+          
lang

+          
An optional value for the default text-processing language used by this service.

         
       

       
For instance, a service could expose the following minimal service manifest:
@@ -929,7 +931,8 @@ 
Text-processing language

         
All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit 
         text-processing language in a lang field. The lang 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: name, description,
         query (for reconciliation queries), v and str (for property values). Nested objects inherit the text-processing language of their parent, and can override it by setting their own lang value
-        (see example below). Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.

+        (see example below). A default text-processing language for any natural language string returned or processed by a service MAY be set in the lang field of the service manifest.
+        Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.

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

 
@@ -937,7 +940,6 @@ 
Text-processing language

           

         

 
-        
If no explicit text-processing language is given, the first language of the intended audience returned by the service is considered the default text-processing language.

       

     

     


From d2ca1e6b4cbc0f3e51523acc78b776fab8be8d3f Mon Sep 17 00:00:00 2001
From: Fabian Steeg 
Date: Tue, 12 Dec 2023 12:00:04 +0100
Subject: [PATCH 4/5] Clarify requirements for language headers (#136)

Based on our discussion in the September meeting:

https://etherpad.lobid.org/p/reconciliation-september-2023
---
 draft/index.html | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/draft/index.html b/draft/index.html
index f12b16a..b35efb7 100644
--- a/draft/index.html
+++ b/draft/index.html
@@ -917,8 +917,10 @@ 
Internationalization Considerations

       

         
Language of the intended audience

         

-           Following [[RFC9110]], services SHOULD support the Accept-Language 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 Content-Language 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.
+           Following [[RFC9110]], services SHOULD support the Accept-Language header to let clients specify the preferred language in which user-facing text is returned.
+           If clients set the Accept-Language header, the requested language(s) MUST be provided as well-formed [[BCP 47]] language tags.
+           Services MAY use the Content-Language header in their responses to expose the language(s) of the intended audience(s) of each response.
+           If services set the Content-Language header, they MUST use valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] tags.
         

         

           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,

From b400ac9a87f758a4a8d5fe373c96e07aba398eca Mon Sep 17 00:00:00 2001
From: Fabian Steeg 
Date: Tue, 12 Dec 2023 12:59:28 +0100
Subject: [PATCH 5/5] Add section to define the two types of language
 declaration (#136)

Based on the W3C docs: https://www.w3.org/TR/international-specs/ &
https://www.w3.org/International/questions/qa-text-processing-vs-metadata
---
 draft/index.html | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/draft/index.html b/draft/index.html
index b35efb7..3ea52e6 100644
--- a/draft/index.html
+++ b/draft/index.html
@@ -914,10 +914,20 @@ 
Data Extension Responses

     

     

       
Internationalization Considerations

+      
The following sections rely on terminology from the W3C internationalization best practices for spec developers,
+        in particular on the distinction of two types of language declaration:

+      

+        The language of the intended audience, also referred to as language metadata, is used to describe the language(s) of the intended audience of resources as a whole. In the context of reconciliation,
+        this is relevant e.g. for setting the user interface language in a reconciliation client, providing user-facing text in the user's preferred language.
+      

+      

+        The text-processing language on the other hand declares the single language in which a specific range of text is actually written in, to support features like text-to-speech, spell checking, or hyphenation.
+        In the context of reconciliation, this distinction is importat since the actual data being reconciled will often be in a different language than the client's user interface.
+      

       

         
Language of the intended audience

         

-           Following [[RFC9110]], services SHOULD support the Accept-Language header to let clients specify the preferred language in which user-facing text is returned.
+           Following [[RFC9110]], services SHOULD support the Accept-Language header to let clients specify the language of the intended audience in which user-facing text is returned.
            If clients set the Accept-Language header, the requested language(s) MUST be provided as well-formed [[BCP 47]] language tags.
            Services MAY use the Content-Language header in their responses to expose the language(s) of the intended audience(s) of each response.
            If services set the Content-Language header, they MUST use valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] tags.
@@ -930,8 +940,8 @@ 
Language of the intended audience

       

         
Text-processing language

 
-        
All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit 
-        text-processing language in a lang field. The lang 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: name, description,
+        
All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit text-processing language in a lang field.
+        The lang 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: name, description,
         query (for reconciliation queries), v and str (for property values). Nested objects inherit the text-processing language of their parent, and can override it by setting their own lang value
         (see example below). A default text-processing language for any natural language string returned or processed by a service MAY be set in the lang field of the service manifest.
         Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.