Architecture of localized text

Location of schema.display.properties files

For a given InsuranceSuite application, the "schema.display.properties" files are stored in the /modules/configuration/config/locale directory.

• There is one default file named schema.display.properties.
  • This file contains schema information in English.
• There is one schema.display_LOCALE.properties file for each locale. Each file contains schema information for that locale. For example:
  • The schema.display_fr.properties file contains schema information in French.
  • The schema.display_es.properties file contains schema information in Spanish (for Latin American locales).
  • The schema.display_es_ES.properties file contains schema information in Spanish (for Spain).

In a given situation, if the locale is not English but the given display value cannot be found for the desired locale, the value in the default schema.display.properties is used. If for some reason the value cannot be found in the default schema.display.properties either, the text from the corresponding schema file property is used. For example, if localized text for an API title cannot be found in any schema.display file, the value of the schema file's title property is used.

The schema.display.properties files can be viewed in Studio by accessing the config > Localizations > Resource Bundle 'schema.display' node.

Note that the base configuration does provide schema.display_LOCALE.properties files for several locales, but these files may not be complete. Before using them in a production environment, Guidewire recommends reviewing the contents to verify completeness and correctness of the translations.

schema.display.properties keys

Every schema localization file contains a series of key/value pairs. For example:

json.common.v1.definitions.Activity.properties.activityType.description = 
The type of this activity, such as `general` or `approval`

The key is the text that comes before the "=". It defines a piece of localizeable text in a locale-generic way. Keys for schema information are written in the following way:

• Keys for values defined in a schema.json file start with json.
• Keys for values defined in a swagger.yaml file start with swagger.
• The remainder is a dot-notation string that follows a specific pattern to identify the corresponding schema component, such as "common.v1.definitions.Activity.properties.activityType.description".

Each key must adhere to a specific pattern in order to be associated with the correct schema element. In most cases, the pattern for the key corresponds to the path to the localized property within the schema file. But there are additional nuances to the patterns. For more information, see Associating display keys with API elements.

schema.display.properties values

The value is the localized text to use for that key when the user is working in the given locale. For example, suppose the key/value pair for the description of an Address is as follows:

json.common.v1.definitions.Address.description = An `Address` represents a postal address. The
fields available on an `Address` will depend upon the `country` value for the `Address`.

If a key must be shown in multiple languages, then it is defined in each locale-specific file as needed. The key remains constant across all files. Only the value varies.

For example, the following key/value pairs come from the default schema.display.properties file:

json.common.v1.definitions.Address.properties.CEDEX.description = The CEDEX bureau of the address. 
Only applicable in certain countries.

The following key/value pairs come from the base configuration schema.display_fr.properties file:

json.common.v1.definitions.Address.properties.CEDEX.description = Bureau CEDEX de l'adresse. 
Applicable uniquement dans certains pays.

Determining which value to use

Cloud API returns API definition documentation through:

• The /openapi.json and /swagger.json endpoints in each API.
• The schemas returned by the Cloud API-specific /job/v1/graph-schema and /claim/v1/graph-schema endpoints.

When calling these endpoints, the request object can include a GW-Language header set to a given language, such as "fr_FR". For more information on this header, see Globalization.

When the GW-Language header is present, Cloud API attempts to return API definition documentation in the request language. For each piece of documentation, a localized value is returned if all of the following are true:

• There is a schema.display.properties file for that language.
• The schema.display.properties file defines a value for the corresponding key.

In all other circumstances, a default value is used. The value defined in the default schema.display.properties file is used, if it exists. If it does not exist, the corresponding value from the schema definition file itself is used.

For example, suppose an InsuranceSuite application has an Address schema that includes properties for addressLine1, arrondissement, and CEDEX. The following information exists in each of the following files:

The schema definition file

"Address": {
  ...
  "properties": {
    "addressLine1": {
      "description": "The first line of the address",
      "type": "string",
    },
    "arrondissement_Ext": {
      "description": "The administrative district of the address. Used in certain large 
                      French cities, in particular Paris.",
      "type": "string",
    },
    "CEDEX": {
      "description": "The CEDEX bureau of the address. Only applicable in certain countries.",
      "type": "string",
      }

The schema.display.properties file

json.common.v1.definitions.Address.properties.addressLine1.description = The first line of the 
address, such as "123 Main Street"
json.common.v1.definitions.Address.properties.CEDEX.description = The CEDEX bureau of the 
address. Only applicable in certain countries.

The schema.display_fr.properties file:

json.common.v1.definitions.Address.properties.CEDEX.description = Bureau CEDEX de l'adresse. 
Applicable uniquement dans certains pays.

Now, suppose a caller requests schema information in French for the following keys:

• json.common.v1.definitions.Address.properties.CEDEX.description
• json.common.v1.definitions.Address.properties.Address.description
• json.common.v1.definitions.Address.properties.Arrondissement_Ext.description

Cloud API returns the following values:

• First key
  • Return value: "Bureau CEDEX de l'adresse. Applicable uniquement dans certains pays."
  • Reason: There is a schema,display.properties file for French and the file defines this key.
• Second key
  • Return value: "The first line of the address, such as "123 Main Street"
  • Reason: Even though there is a schema,display.properties file for French, the file does not define this key. However, the key is defined in the default schema,display.properties file.
• Third key
  • Return value: "The administrative district of the address. Used in certain large French cities, in particular Paris."
  • Reason: The key is not defined in either the locale-specific schema,display.properties file or the default schema,display.properties file. Therefore, the value of the description property in the schema definition is returned.