Add section on text-processing language (#52)

reconciliation-api · Jul 13, 2023 · 93a35dd · 93a35dd
1 parent 1070550
commit 93a35dd
Show file tree

Hide file tree

Showing 5 changed files with 54 additions and 5 deletions.
diff --git a/draft/examples/data-extension-response/valid/example-full.json b/draft/examples/data-extension-response/valid/example-full.json
@@ -30,7 +30,8 @@
           "id": "variantName",
           "values": [
             {
-              "str": "Stryi-Leitgeb, Gerda"
+              "str": "Stryi-Leitgeb, Gerda",
+              "lang": "de"
             },
             {
               "str": "Leitgeb, Gerda Stryi-"
@@ -55,7 +56,8 @@
             },
             {
               "id": "4033430-2",
-              "name": "Künstlerin"
+              "name": "Künstlerin",
+              "lang": "de"
             }
           ]
         },

diff --git a/draft/examples/reconciliation-query-batch/valid/text-processing-language.json b/draft/examples/reconciliation-query-batch/valid/text-processing-language.json
@@ -0,0 +1,19 @@
+{
+  "queries": [
+    {
+      "query": "Deng Shuping",
+      "lang": "en",
+      "properties": [
+        {
+          "pid": "professionOrOccupation",
+          "v": "art historian"
+        },
+        {
+          "pid": "variantName",
+          "v": "鄧淑蘋",
+          "lang": "zh-Hant"
+        }
+      ]
+    }
+  ]
+}
diff --git a/draft/index.html b/draft/index.html
@@ -91,6 +91,11 @@
             "publisher": "W3C",
             "href": "https://www.w3.org/standards/webdesign/accessibility"
           },
+          "BCP 47": {
+            "title": "Tags for Identifying Languages",
+            "publisher": "IETF",
+            "href": "https://www.rfc-editor.org/rfc/bcp/bcp47.txt"
+          },
         }
       };
     </script>
@@ -908,9 +913,6 @@ <h2>Accessibility Considerations</h2>
         and configuration of <a href="#dfn-data-extension-property-setting">property settings</a>. These user interfaces SHOULD be implemented ensuring [[accessibility]] for all people, whatever their hardware,
         software, language, location, or ability.
       </p>
-      <p class="note">
-        Currently, supporting multiple languages requires separate reconciliation services for each language. For progress on multilingual support in a single service see issue <a href="https://github.com/reconciliation-api/specs/issues/52">#52</a>.
-      </p>
       <section>
         <h3>Visual rendering</h3>
         <p>
@@ -932,6 +934,22 @@ <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>

diff --git a/draft/schemas/data-extension-response.json b/draft/schemas/data-extension-response.json
@@ -79,6 +79,9 @@
                           },
                           "description": {
                             "type": "string"
+                          },
+                          "lang": {
+                            "type": "string"
                           }
                         },
                         "required": [
@@ -92,6 +95,9 @@
                         "properties": {
                           "str": {
                             "type": "string"
+                          },
+                          "lang": {
+                            "type": "string"
                           }
                         },
                         "required": [

diff --git a/draft/schemas/reconciliation-query-batch.json b/draft/schemas/reconciliation-query-batch.json
@@ -55,6 +55,10 @@
             "type": "number",
             "description": "The maximum number of candidates to return"
           },
+          "lang": {
+            "type": "string",
+            "description": "The text-processing language for the query"
+          },
           "properties": {
             "type": "array",
             "description": "An optional list of property mappings to refine the query",