SkySpark by SkyFoundry

13. Localization

Overview

Localization of the Fresco user interface is supported using Fantom's standard localization infrastructure which is covered in Localization.

SkySpark does not currently include any translations for specific locales. Instead we support our partner's in each region to perform these localizations themselves. If you do perform a translation and wish to have it included in the standard distribution please just let us know.

Locale Props Files

Localizable text is organized in prop files called "locale/en.props" in each pod. The sys pod contains localization for core props like time/date formats for most all global locales. However, all other pods will only contain English by default.

When you perform a translation for a specific locale, you will be creating a props file for each pod using the same keys as found in "en.props", but with the values translated to your language.

For example most text associated with Fresco is bundled in fresco.pod in "en.props" using keys like this:

funcs.name=Funcs
files.name=Files
snapshots.name=Snapshots

We override these keys by creating text files with this path format:

etc/{pod}/locale/{locale}.props

If we were to translate the keys above to French, then we would create the file "etc/fresco/locale/fr.props" which redefines these keys:

funcs.name=Fonctions
files.name=Fichiers
snapshots.name=Instantané

Note props file must encoded in UTF-8 when using non-ASCII characters.

Tags

Many end users screens display tag names as column headers or in the info popups and will need localization. Since often it is difficult to associate a specific Fantom pod with a tag definition, we lump tag localization together into one single localization props file under:

etc/proj/tags/{lang}.props

The prop keys are the tag names and the values the localized display name. For example to localize tag names for Spanish:

// file etc/proj/tags/es.props
site=edificio
equip=equipo

The following Fantom APIs can be used for localization of tag names:

The following Axon APIs can be used for localization of tags

For example to localize the column names of a query from Folio:

readAll(site).colsToLocale

LocaleStub

A simple command line tool proj::LocaleStub is provided to stub out props files in the appropiate etc directory. This tool:

  1. reads the "en.props" file from one pod or all the pods
  2. comments out all the keys using //_ start of line
  3. writes it out into the correct etc directory

For example if you wanted to stub out fresco's props for German, you would run:

fan proj::LocaleStub de -pod fresco

Leave off the -pod option to copy props file for every pod that contains an "locale/en.props".

After you created localized files, you can use this tool to run a report on localization keys which have been added/removed between builds:

fan proj::LocaleStub -diff fr

Choosing Locale

The locale used for the user experience is defined by the Accept-Language header sent by the browser. If the user's default locale is not available, then the system will fallback to English.

In the App Menu is also an option which will let you manually switch your locale. The list of available locales is populated from the list of langauges you have configured in your browser options.

Testing Locales

Locale prop files are compiled into a JavaScript file which is generated once on startup and then cached. So even when you change a props file under etc, you will not see the change until you refresh both the server cache and your browser. You can refresh the server either by a restart or by invoking the utility function compileProjEtc() in your Axon console.

During the localization process you can set the "etc/sys/config.props" property "localeTestMode" to "true" to have Fresco display all strings as "pod::key". This can be a convenient way to see what the localization key is for each string displayed in the UI. Note that changing this system property requires a restart of your server to take effect.

Deploying Locales

Once your locale files are configured and tested, you can deploy them as a standard Fantom pod. This is done by creating a pod with a indexed prop using the key "sys.envProps" and a value of your pod name. The pod bundles up your locale files as resource files using the same naming pattern as the "etc" directory.

There is a command tool which will generate the pod source for you by copying all your locale files from etc. For example to copy all the fr.props and generate code to build a localeFr pod:

fan proj::LocaleCompile fr

The output of the command line tool is a source directory with a build script and a copy of all your etc locale files. You can then build this pod and deploy it as an alternate to using etc files.