Locale Preferences

Canopy IIIF supports locale preferences for user interface language. More than one locale can be set as options to allow users to toggle between languages. If only one locale is defined, the language toggle will not render.

The default locale is English.

Properties

The locales property is optional and provides an array of preset Locales for the user interface.

For each Locale, the following properties are required:

Property	Type	Description
`config`	`string`	Path to the locale configuration file.
`label`	`string`	Label for the locale.
`lang`	`string`	BCP 47 language code for the locale.

"locales": [
  {
    "config": "locales/en.json",
    "label": "English",
    "lang": "en"
  }
]

Customizing a Locale

User interface language strings are set through a locale configuration file located in the config/locales directory. Persons customizing a Canopy instance can add new language configurations to support their preferred locales. We welcome all pull requests to add new locales to the Canopy IIIF project.

English configuration is predefined and found at config/locales/en.json

config/locales/en.json

{
  "footerSourceCollection": "Source Collection",
  "footerToggleTheme": "Toggle Theme",
  "homepageHighlightedWorks": "Highlighted Works",
  "searchButton": "Search",
  "searchResults": "Results",
  "searchFilter": "Filter",
  "searchFilterAny": "Any",
  "searchFilterClear": "Clear All",
  "searchFilterClose": "Close",
  "searchFilterSubmit": "View Results"
}

Multiple Locales

If more than one locale is defined in the config/canopy.json, a select element will render in the header allowing users to toggle the defined languages. In addition, Canopy will attempt to align the language set by the user's browser with the available options. As a fallback, the first locale defined in the array will be set.

As an example, if a visitor with en-US visited a Canopy instance that included both no and en as language options, the en locale configuration would be the default locale. Whereas, if a user visited this same instance with fr as their browser language, the default locale would be the no configuration.

"locales": [
  {
    "config": "locales/no.json",
    "label": "Norsk",
    "lang": "no"
  },
  {
    "config": "locales/en.json",
    "label": "English",
    "lang": "en"
  }
]

Example Locale Configuration

In this example configuration, the locales property is set to include both pt and en options. The pt locale is set as preferred locale and will be the default language for the user interface unless the user's browser language is set to en.

config/canopy.json

{
  "collection": "https://sebastiao-lacerda.vercel.app",
  "locales": [
    {
      "config": "locales/pt.json",
      "label": "Português",
      "lang": "pt"
    },
    {
      "config": "locales/en.json",
      "label": "English",
      "lang": "en"
    }
  ]
}

Search Map