622 AppD lang and translations

CHANGELOG.md

@@ -22,6 +22,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
 * Add `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
 * Added `/v2/` paths to the AppD's specification, allowing a single implementation to support serving both FDC3 v1.2 and v2.0 application records, enabling simpler migration ([#666](https://github.com/finos/FDC3/pull/666))
+* Added `lang` field to appD application records to specify the primary language of an app and its appD record. ([#670](https://github.com/finos/FDC3/pull/670))
+* Added `localizedVersions` field to appD application records to support localized versions of descriptive fields in the app records and alternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670))
 
 ### Changed
 * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))

docs/references.md

@@ -14,6 +14,7 @@ The following normative documents contain provisions, which, through reference i
 - **OpenAPI Standard v3.0**, [https://www.openapis.org/].
 - **RFC 2119**, _Keywords for use in RFCs to Indicate Requirement Levels, March 1997_, [https://datatracker.ietf.org/doc/html/rfc2119].
 - **RFC 2782**, _A DNS RR for specifying the location of services (DNS SRV), February 2000_, [https://datatracker.ietf.org/doc/html/rfc2782].
+- **RFC 5646**, _Tags for Identifying Languages, September 2009_, [https://datatracker.ietf.org/doc/html/rfc5646].
 - **TypeScript Programming Language**, [https://www.typescriptlang.org/].
 
 

src/app-directory/specification/appd.yaml

@@ -404,18 +404,7 @@ components:
           format: int32
         message:
           type: string
-    Application:
-      description: >
-        Defines an application retrieved from an FDC3 App Directory, which can
-        then be launched.
-
-        Launching typically means running for a user on a desktop.
-        The details around 'launching' including who or what might do it, and how the launch action is initiated are
-        discussed elsewhere in the FDC3 App Directory spec.
-      required:            # details are not required as the host type applications use the hostsManifests mapping instead
-        - appId
-        - name
-        - type
+    BaseApplication:
       properties:
         appId:
           type: string
@@ -455,6 +444,10 @@ components:
         tooltip:
           type: string
           description: Optional tooltip description e.g. for a launcher
+        lang:
+          type: string
+          pattern: '^[a-z]{2}(-[a-zA-Z0-9]{2,8}){0,1}$'
+          description:  a language tag that specifies the primary language of both application and its AppD entry, as defined by IETF RFC 5646.
         description:
           type: string
           description: >-
@@ -501,6 +494,24 @@ components:
             $ref: '#/components/schemas/Intent'
         hostManifests:
           $ref: '#/components/schemas/HostManifests'
+    Application:
+      description: >
+        Defines an application retrieved from an FDC3 App Directory, which can
+        then be launched.
+
+        Launching typically means running for a user on a desktop.
+        The details around 'launching' including who or what might do it, and how the launch action is initiated are
+        discussed elsewhere in the FDC3 App Directory spec.
+      required:            # details are not required as the host type applications use the hostsManifests mapping instead
+        - appId
+        - name
+        - type
+      allOf:
+        - $ref: '#/components/schemas/BaseApplication'
+        - type: object
+          properties:
+            localizedVersions:
+              $ref: '#/components/schemas/LocalizedVersions'
     ApplicationV1:
       description: >
         (Deprecated v1 API version) Defines an application retrieved from an FDC3 App Directory, which can
@@ -745,6 +756,15 @@ components:
       type: object
       description: >-
         Object containing all host specific properties.
+    LocalizedVersions:
+      type: object # keys should be constrained to valid language tags '^[a-z]{2}(-[a-zA-Z0-9]{2,8}){0,1}$' - not possible to express in OpenAPI without moving to v3.1.0 and the javascript/jsonschema version
+      description: >
+        Provides localized alternatives to any field of the AppD record, which may also refer to an alternative
+        version of the application that is also localized (e.g. by providing customConfig or an alternative URL). 
+        The keys to this object should be language tags as defined by IETF RFC 5646, e.g. en, en-GB or fr-FR.
+      additionalProperties:
+        x-additionalPropertiesName: Language tag
+        $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers.
   examples:
     FDC3WorkbenchAppDefinition:
       value:
@@ -754,6 +774,7 @@ components:
         description: Development and test tool for FDC3 desktop agents and apps
         version: 1.0.0
         tooltip: FDC3 Workbench
+        lang: en-US
         icons:
           - src: http://fdc3.finos.org/toolbox/fdc3-workbench/fdc3-icon-256.png
         images:
@@ -820,6 +841,12 @@ components:
           },
           Web App Manifest: https://example.com/fdc3-workbench.json
         }
+        localizedVersions: {
+          fr-FR: {
+            title: FDC3 Table de travail,
+            description: Outil de développement et de test pour les desktop agents et applications FDC3
+          }
+        }
       summary: A sample app definition for the FDC3 Workbench application
     FDC3WorkbenchAppDefinitionSearchResponse:
       value:

website/package.json

@@ -26,7 +26,7 @@
     "del-cli": "4.0.1",
     "docusaurus": "1.14.7",
     "docusaurus-delete-version": "0.1.1",
-    "redoc-cli": "0.10.1",
+    "redoc-cli": "0.13.10",
     "replace-in-files-cli": "1.0.0",
     "replace-json-property": "1.6.3",
     "rimraf": "3.0.2"

website/static/schemas/next/app-directory.yaml

@@ -404,18 +404,7 @@ components:
           format: int32
         message:
           type: string
-    Application:
-      description: >
-        Defines an application retrieved from an FDC3 App Directory, which can
-        then be launched.
-
-        Launching typically means running for a user on a desktop.
-        The details around 'launching' including who or what might do it, and how the launch action is initiated are
-        discussed elsewhere in the FDC3 App Directory spec.
-      required:            # details are not required as the host type applications use the hostsManifests mapping instead
-        - appId
-        - name
-        - type
+    BaseApplication:
       properties:
         appId:
           type: string
@@ -455,6 +444,10 @@ components:
         tooltip:
           type: string
           description: Optional tooltip description e.g. for a launcher
+        lang:
+          type: string
+          pattern: '^[a-z]{2}(-[a-zA-Z0-9]{2,8}){0,1}$'
+          description:  a language tag that specifies the primary language of both application and its AppD entry, as defined by IETF RFC 5646.
         description:
           type: string
           description: >-
@@ -501,6 +494,24 @@ components:
             $ref: '#/components/schemas/Intent'
         hostManifests:
           $ref: '#/components/schemas/HostManifests'
+    Application:
+      description: >
+        Defines an application retrieved from an FDC3 App Directory, which can
+        then be launched.
+
+        Launching typically means running for a user on a desktop.
+        The details around 'launching' including who or what might do it, and how the launch action is initiated are
+        discussed elsewhere in the FDC3 App Directory spec.
+      required:            # details are not required as the host type applications use the hostsManifests mapping instead
+        - appId
+        - name
+        - type
+      allOf:
+        - $ref: '#/components/schemas/BaseApplication'
+        - type: object
+          properties:
+            localizedVersions:
+              $ref: '#/components/schemas/LocalizedVersions'
     ApplicationV1:
       description: >
         (Deprecated v1 API version) Defines an application retrieved from an FDC3 App Directory, which can
@@ -745,6 +756,15 @@ components:
       type: object
       description: >-
         Object containing all host specific properties.
+    LocalizedVersions:
+      type: object # keys should be constrained to valid language tags '^[a-z]{2}(-[a-zA-Z0-9]{2,8}){0,1}$' - not possible to express in OpenAPI without moving to v3.1.0 and the javascript/jsonschema version
+      description: >
+        Provides localized alternatives to any field of the AppD record, which may also refer to an alternative
+        version of the application that is also localized (e.g. by providing customConfig or an alternative URL). 
+        The keys to this object should be language tags as defined by IETF RFC 5646, e.g. en, en-GB or fr-FR.
+      additionalProperties:
+        x-additionalPropertiesName: Language tag
+        $ref: '#/components/schemas/BaseApplication'
   examples:
     FDC3WorkbenchAppDefinition:
       value:
@@ -754,6 +774,7 @@ components:
         description: Development and test tool for FDC3 desktop agents and apps
         version: 1.0.0
         tooltip: FDC3 Workbench
+        lang: en-US
         icons:
           - src: http://fdc3.finos.org/toolbox/fdc3-workbench/fdc3-icon-256.png
         images:
@@ -820,6 +841,12 @@ components:
           },
           Web App Manifest: https://example.com/fdc3-workbench.json
         }
+        localizedVersions: {
+          fr-FR: {
+            title: FDC3 Table de travail,
+            description: Outil de développement et de test pour les desktop agents et applications FDC3
+          }
+        }
       summary: A sample app definition for the FDC3 Workbench application
     FDC3WorkbenchAppDefinitionSearchResponse:
       value: