[RCP-44] Supporting Multiple Metadata Locales

[darnjo]

Discussed in #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:

• Supporting Multiple Metadata Locales #59 (comment)
• Supporting Multiple Metadata Locales #59 (reply in thread)

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. Done
• Consideration of languages other than those supported by UTF-8. UTF-8 can encode all languages.
• 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.

If we are extending DisplayNames to Lookup, shouldn't we amend the definition of Lookup?

[darnjo]

TODOs for this item:

• There have been two verified implementations by different providers.
• Need to turn the text above in to the formal spec and create testing rules and have them approved in Certification.
• This proposal depends on "Shapes" (aka OData Complex Types), which aren't supported in the DD at this time and won't be until 2.2.

[darnjo]

If we are extending DisplayNames to Lookup, shouldn't we amend the definition of Lookup?

@cobogeri - yes. Good point. We will need to change the definition of Lookup.