Mno-enterprise and Impac! i18n guidelines

This document describes the guidelines to follow to implement i18n mno-enterprise & Impac! projects.

Overview

• mno-enterprise-angular uses mno-enterprise API and download locale file from it.
• Impac-angular uses mno-enterprise API and Impac! API. Impac-angular locale files are downloaded from mno-enterprise.

Frontend implementation

Configuration

Both mno-enterprise-angular and impac-angular should use angular-translate library.

Here is an example on how to configure angular-translate on the mno-enterprise-angular project:

@app.constant('LOCALES', {
  'locales': [
    { id: 'en-gb', name: 'English (UK)' },
    { id: 'zh-ch', name: 'Chinese (China)' }
  ],
  'preferredLocale': 'en-gb',
  'fallbackLanguage': 'en-gb'
})

@app.config(($translateProvider, LOCALES) ->
  # Path to translations files
  $translateProvider.useStaticFilesLoader({
    prefix: '/locales/',
    suffix: '.locale.json'
  })

  $translateProvider.fallbackLanguage(LOCALES.fallbackLanguage)
  $translateProvider.useSanitizeValueStrategy('sanitizeParameters')
  $translateProvider.useMissingTranslationHandlerLog()
)

The configuration of angular-translate should use the `angular-translate-loader-static-files` module to configure where the files are stored and load them when app initialise.

The frontend should load the locale used in the path or a default locale. Here is an example of how to implement it in mno-enterprise-angular:

# Configure angular translate depending on the locale used in the path
@app.run(($window, $translate, LOCALES) ->
  # Get current path (eg. "/en-gb/dashboard/" or "/dashboard/")
  path = $window.location.pathname

  # Extract the language code if present
  re = /^\/([A-Za-z]{2}-[A-Za-z]{2})\/dashboard\//i
  found = path.match(re)

  if found?
    # Ex found: ["/en-gb/dashboard/", "en-gb", index: 0, input: "/en-gb/dashboard/"]
    locale = found[1]
  else
    # Default language
    locale = LOCALES.preferredLocale

  $translate.use(locale)
)

Impac-angular should be able to receive i18n configuration instruction from mno-enterprise-angular. This could be done by extending the current impac-angular configuration. The current locale used (given by angular-translate using `$translate.use()` accessor) should be passed to impac-angular for it to load asynchronously the right locale file from mno-enterprise backend.

mno-enterprise locale json file and locale impac json file should be 2 different files.

Backend implementation

Localized URL

The URL should be localised in order for the customers to copy and paste URL and keep the localisation when the page is loaded. If the locale is missing in the URL, a default locale must be loaded (eg. "en-gb").

• Default URL: https://mno-project.com.au
• English forced URL: https://mno-project.com.au/en-gb/
• Chinese forced URL: https://mno-project.com.au/zh-ch/

mno-enterprise configuration

• Enable i18n in config/initializers/mno_enterprise.rb:

# I18n - Controls:
#   - Routing in development
#   - Filter and locale management in controllers
config.i18n_enabled = true

• Wrap MnoEnterprise::Engine routes in config/routes.rb:

# MnoEnterprise Engine
scope '(:locale)' do
  mount MnoEnterprise::Engine, at: '/mnoe', as: :mno_enterprise
end

• NGinx will need to be configured in UAT and production to accept localised URIs (sample)

i18n files generation

Local files should be stored in .yml files format in the folder mno-enterprise/config/locales/ folder.

mno-enterprise gem contains a tool to convert multiple en-gb.yml files into one json file en-gb.locale.json:

$ rake mnoe:locale:generate

As an example, en-gb.yml file:

en-gb:
  mno_enterprise:
    templates:
      dashboard:
        account:
          my_account: My Account
          personal_information: Personal Information
          user_form_name: Name
          user_form_surname: Surname

will be converted to public/locale/en-gb.locale.json:

{
  "mno_enterprise.templates.dashboard.account.my_account": "My Account",
  "mno_enterprise.templates.dashboard.account.personal_information": "Personal Information",
  "mno_enterprise.templates.dashboard.account.user_form_name": "Name",
  "mno_enterprise.templates.dashboard.account.user_form_surname": "Surname"
}