Skip to content

Locale module (Localization)

This package provides localization features:

  • Translations of Labels: with the template func __() (which uses
  • Local display of Dates (In local timezone or given timezone): with the template func dateTimeFormat or dateTimeFormatFromIso
  • Local display of prices and numbers: with the template func priceFormat and numberFormat (Using


  locale: en-gb                                    # the locale used for labels
  fallbackLocales:                                 # a list of (optional) locales that should be used for fallback
  - en-gb
  translationFile: translations/en_GB.all.json     # the label file location
  translationFiles:                                # or a list of label file locations
  - translations/merged/en-gb.all.yaml
  - translations/translated/en-gb.adjusted.yaml
    default:                                    # configure display of prices
        thousand: ','
        decimal: '.'
        formatZero: '%s -.-'
        format: "%v %s"
    GBP:                                        # configure display of prices in currency GBP
        thousand: ','
        decimal: '.'
        formatZero: '%s -.-'
        format: "%v %s"
  numbers:                                         # configure display of numbers
    thousand: ','
    decimal: '.'
    precision: 2
    dateFormat:  02 Jan 2006
    timeFormat: 15:04:05
    dateTimeFormat: 02 Jan 2006 15:04:05
    location: LOCATIONCODE                          # required for formatLocaleTime

By providing different configurations for the different configuration areas (see prefixrouter module) you can easily build multilanguage applications.

Usage in Templates:

Localisation of Labels:

  # Display the label for the given key:

  # Display the label and pass a default that is used if the key is not existent in a labelfile

    # Display the label with dynamic values replaces:
    __("key").setDefaultLabel("Hello Mr {{.UserName}}").setTranslationArguments({UserName: "Max"})

    # Support the usage of plural labels idepending on a given count:

    # Force the usage of another local by passing languange code as 5th paramater:

Proposed organisation of label files:

We propose to put the translations in a folder translations like this:

└───src (put the original label files here. This is where developers should work.)
└───merged (contains the generated files)
└───translated (optional - can contain the files returned from a translation tool or agency)

The label files in translations/src can either be json or yaml. Example:

    "id": "attribute.clothingSize",
    "translation": "Size"
    "id": "error404.headline",
    "translation": "Page not found!"

You can then run this command to generate the merged label file for the contained language codes:

goi18n merge -sourceLanguage en-us -format yaml -outdir translations/merged/ translations/src/*.json

Read more about label files and translation workflows here:

Formatting of dates:

Two template functions are provided:

  • dateTimeFormatFromIso - can get an ISO date format and returns the formatter object
  • dateTimeFormat - need to get a go time.Time object as input and returns the formatter

The formatter can format a date in the configured format - either in the timezone passed - or converted to the local timezone.



Other functions are formalToLocalDate() or formatTime() etc..

Note: For displaying locale formats set the correct date locationcode - see

Formatting of prices:

// £ 90.25
// $ 42,049.99 USD

Formatting of numbers:

Formatting of numbers can be configured like described above. The delimiter for thousand and decimal can be configured. The precision for the decimal places can be configured with a default value, but can also be overwritten.

// with defaul precision
// with overwritten precision
numberFormat(12300, 2)