[RCP-44] Supporting Multiple Metadata Locales

[darnjo]

Discussed in https://github.com/RESOStandards/transport/discussions/59

Option 3: DisplayName Complex Type It was mentioned on the November 8, 2022 Transport call that perhaps we could use Complex Types to avoid having to repeat data or join on a normalized structure.

See the following comments for more information:

• https://github.com/RESOStandards/transport/discussions/59#discussioncomment-4080668
• https://github.com/RESOStandards/transport/discussions/59#discussioncomment-4081241

We probably want to change the format a bit from the initial suggestion, for one not have things keyed by locale codes and making the display names into a list so their shape is more normal (regular) and easier to query.

<ComplexType Name="I18nString">
  <Property Name="Locale" Nullable="false" Type="Edm.String" />
  <Property Name="Value" Nullable="false" Type="Edm.String" />
</ComplexType>

<EntityType Name="Field">
  ...
  <Property Name="FieldKey" Type="Edm.String" />
  <Property Name="FieldName" Type="Edm.String" />
  <Property Name="DisplayNames" Type="Collection(I18nString)" />
  ...
</EntityType>

This would allow for querying as well using any and all.

GET /Field?$filter=DisplayNames/any(item: item/Locale in ('en-CA', 'fr-CA'))
{
  "@odata.context": "/Field?$filter=DisplayNames/any(item: item/Locale in ('en-CA', 'fr-CA'))",
  "value": [
    {
      "FieldKey": "f1",
      "FieldName": "ListPrice",
      "DisplayNames": [
        {
          "Locale": "en-CA",
          "Value": "List Price"
        },
        {
          "Locale": "fr-CA",
          "Value": "Liste des Prix"
        }
      ]
    }
  ]
}

This would also work with Lookups:

<ComplexType Name="I18nString">
  <Property Name="Locale" Nullable="false" Type="Edm.String" />
  <Property Name="Value" Nullable="false" Type="Edm.String" />
</ComplexType>

<EntityType Name="Lookup">
  ...
  <Property Name="LookupKey" Type="Edm.String" />
  <Property Name="LookupName" Type="Edm.String" />
  <Property Name="LookupValue" Type="Edm.String" />
  <Property Name="DisplayNames" Type="Collection(I18nString)" />
  ...
</EntityType>

GET /Lookup?$filter=DisplayNames/any(item: item/Locale in ('en-CA', 'fr-CA'))
{
  "@odata.context": "/Lookup?$filter=DisplayNames/any(item: item/Locale in ('en-CA', 'fr-CA'))",
  "value": [
    {
      "LookupKey": "l1",
      "LookupName": "StandardStatus",
      "LookupValue": "Pending",
      "DisplayNames": [
        {
          "Locale": "en-CA",
          "Value": "Pending"
        },
        {
          "Locale": "fr-CA",
          "Value": "En Attente"
        }
      ]
    }
  ]
}

TODOs

• Lock down the Locale property so that it only accepts ISO Primary Locales, but still supports additional custom locales as per the ISO standard.
• Consideration of languages other than those supported by UTF-8.
• Consider adding a field for the Field and Lookup resource that indicates whether a given item has translations available.

[psftc]

The country code is defined as upper case in the ISO 3166 documentation. We should follow this standard. so en-ca should be en-CA etc.

[darnjo]

The country code is defined as upper case in the ISO 3166 documentation. We should follow this standard. so en-ca should be en-CA etc.

Thanks, Paul. The examples have been updated.