Replies: 5 comments 8 replies
-
|
Option #3: Complex Type added to existing resources Add a complex type to Field and lookup that allows for all translations to be exposed in a single resource. The existing |
Beta Was this translation helpful? Give feedback.
-
|
I think using a complex type would be good here, but I don't think we can make it keyed by locale codes unless our standard shape included all possible locale codes? Also, it becomes interesting to query, if needed. I believe it might make sense to model these as a flat shape similar to the "Translation" field in #37? This would allow for querying as well using any and all. This would also work with Lookups: |
Beta Was this translation helpful? Give feedback.
-
|
You still want Lookup to have a |
Beta Was this translation helpful? Give feedback.
-
|
We don't have DisplayName in any payloads at the moment. |
Beta Was this translation helpful? Give feedback.
-
|
I thought Lookup/Field resources were going to be ratified before Internationalization. Is that not the case? |
Beta Was this translation helpful? Give feedback.
-
|
The Field and Lookup resources were already added to the DD in 1.7 and we have people using Lookup at the moment, but not Field. For Lookup, the LookupValue needs to be preserved since there's existing usage:
For Field, which has DisplayName, there's no usage yet, so we could omit it.
|
Beta Was this translation helpful? Give feedback.
-
|
We're implementing something similar right now which look like this. Each resource has a The
For a given resource (e.g. a Property). {
"listingKey": "123",
"publicRemarks": "These are my public remarks.",
"localizations": [
{
"localizationKey": "Property.123.PublicRemarks.fr-ca",
"resourceName": "Property",
"resourceKey": "123",
"resourceField": "PublicRemarks",
"localizationCulture": "fr-ca",
"localizationText": "Voici mes remarques publiques."
},
{
"localizationKey": "Property.123.PublicRemarks.en-ca",
"resourceName": "Property",
"resourceKey": "123",
"resourceField": "PublicRemarks",
"localizationCulture": "en-ca",
"localizationText": "These are my public remarks."
}
]
}For a lookup it looks like this. {
"lookupKey": "ImageOf.Staircase",
"lookupName": "ImageOf",
"lookupValue": "Staircase",
"localizations": [
{
"localizationKey": "Lookup.ImageOf.Staircase.LookupValue.en",
"resourceName": "Lookup",
"resourceKey": "ImageOf.Staircase",
"resourceField": "LookupValue",
"localizationCulture": "en",
"localizationText": "Staircase",
"localizationAlternativeText": "Staircase"
},
{
"localizationKey": "Lookup.ImageOf.Staircase.LookupValue.fr",
"resourceName": "Lookup",
"resourceKey": "ImageOf.Staircase",
"resourceField": "LookupValue",
"localizationCulture": "fr",
"localizationText": "Escalier",
"localizationAlternativeText": "Escalier"
}
]
}This is not yet in production and we will certainly make changes to it but it may help this discussion. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks so much for posting this. We'll add it to the December 2022 Transport agenda for review. Hopefully you can attend? Contact info at reso.org if you need an invitation. |
Beta Was this translation helpful? Give feedback.
-
|
My pleasure, that's something I discussed with Paul and @grispin at the RESO fall conference. The meeting is in my agenda, hopefully I can attend this time. I saw this thread from the meeting notes. |
Beta Was this translation helpful? Give feedback.
-
|
Happy to chat if you can't make the meeting. You can reach out to [email protected]. Regarding the first example, it looks a bit like Option 2 and 3 here: #37 (comment) In terms of Lookups, the goal is to design a structure that's compatible with the existing Lookup Resource, which currently has adoption. https://ddwiki.reso.org/display/DDW17/Lookup+Resource The examples shown above are compatible with this outside of the specific field names. It has As to whether we name things "Translations" or "Localizations" is totally flexible. |
Beta Was this translation helpful? Give feedback.
-
|
@jeremiethibeault-centris What is the purpose of the 'localizationAlternativeText' field? |
Beta Was this translation helpful? Give feedback.
-
|
In some cases it is used as a short name like in this example. {
"localizationAlternativeText": "Ret. Home",
"localizationCulture": "en",
"localizationKey": "Lookup.CurrentUse.SeniorResidence.LookupValue.en",
"localizationText": "Seniors' residence",
"resourceField": "LookupValue",
"resourceKey": "CurrentUse.SeniorResidence",
"resourceName": "Lookup"
} |
Beta Was this translation helpful? Give feedback.
-
|
TODOs:
|
Beta Was this translation helpful? Give feedback.
-
Summary
There is a need to be able to convey field display name and lookup value metadata in alternate translations. This is different from the translations outlined in #37, which apply to the data in a given payload rather than its metadata.
Requirements
Proposal
There are at least two possible approaches:
Option 1: Metadata Translations using the Field and Lookup Resources
The Data Dictionary has been working towards having definitions in the Field and Lookup resources, which also coincides with the spreadsheet format in the DD specification for 1.7+.
At the current time, new translations are added as additional "columns" in the sheet. For example, SpanishDisplayName in the Fields sheet. If this approach were taken with the Field resource, then the schema would change each time a translation is added or removed.
Similar is true with the Lookups sheet, in which there is also a column for SpanishLookupValue.
Is it possible to use the Field and Lookup resources and have the representation of metadata translations be vertical?
It seems that as long as the uniqueness constraint is present on the keys, then it should be possible to add a "Locale" column to each resource and offer one row per locale.
Field Resource
Example 1: Request All Metadata from the Field Resource
REQUEST
RESPONSE
Example 2: Querying the Field Resource for a Single Locale
REQUEST
RESPONSE
Example 3: Querying the Field Resource for Multiple Locales
REQUEST
RESPONSE
Lookup Resource
The queries for the Lookup Resource would be similar to those of the Field Resource if it were extended with a Locale field.
Example 1: Request All Metadata from the Lookup Resource
REQUEST
RESPONSE
Example 2: Querying the Lookup Resource for a Single Locale
REQUEST
RESPONSE
Example 3: Querying the Lookup Resource for Multiple Locales
REQUEST
RESPONSE
Summary: Field and Lookup Resource
This approach accomplishes the goal of "ease-of-use," since querying is natural, and allows for the entire resource to be replicated when bulk transfers and syncing are needed. It also works in a live query scenario and allows providers to advertise metadata for standard or local resources, fields, or lookups using their existing schema.
One potential drawback is data duplication - if a provider has multiple translations for the same field, it would show up in a separate row and therefore any other attributes would also need to be duplicated.
Something to keep in mind is that RESO resources are interfaces. If the provider wants to store the information in a different way behind the scenes to optimize things like multiple translations, they can do so.
Not having to look in another resource for additional translations is potentially easier for consumers and also reuses existing resources rather than adding new ones.
Option 2: Add Additional Translation Resources
Another possibility is to add one or more translation resources, depending on whether fields and lookups can be commingled.
In the interest of keeping the number of resources small, a single Translation Resource is shown in the following examples.
Example 1: Request All Metadata from the Translation Resource
REQUEST
RESPONSE
Example 2: Querying the Translation Resource for a Single Locale
REQUEST
RESPONSE
Example 3: Querying the Translation Resource for Multiple Locales
REQUEST
RESPONSE
Summary: Translation Resource
Using a separate resource for translations helps to separate concerns and minimizes duplication of data in the Field and Lookup resources.
Something to keep in mind is that the RESO Web API is an interface and providers may store system data in whatever format they feel is best to optimize storage or performance and avoid duplication.
Querying the Translation Resource is fairly straightforward, though it also means additional queries and processing are needed to tie the Field and Lookup Resource data together with their translations.
While this can easily be accomplished during replication, it's not as easy in the live query scenario since the consumer would have to make an additional request and correlate the Field and Lookup data back to the corresponding Translation data on the fly.
Another option would be to separate Field and Lookup translations into their own FieldTranslation and LookupTranslation resources, in which case the
TranslationTypeandTranslationTypeKeyabove would be removed and there would be aFieldKeyandLookupKeyinstead.To add, with the Lookup Resource, the human friendly value is intended to be present in the "LookupValue" field rather than in a separate resource (i.e. Translation), so this would result in values potentially being present in two locations requiring two separate ways to query them. This is something that should be addressed should the Translation Resource option be preferred.
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:
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.
This would allow for querying as well using any and all.
This would also work with Lookups:
Beta Was this translation helpful? Give feedback.
All reactions