Plato leverages the localisation abstractions offered out of the box with .NET Core. This means localisation should be very familiar to .NET Developers. Due to the unique modular design of Plato thee are some important things to consider when thinking about localisation.

Localisation is module specific

Each module within Plato comes with it's own unique set of self-contained localisation files. Localisation files for modules can be found within the Locales folder within the root of each module directory.

Localising a Module

In this example we'll examine the localisation files offered with Plato.Discuss however all modules offered within Plato follow a consistent localisation pattern so this information will also apply to all other official modules.

Taking a look inside the Modules\Plato.Discuss\Locales folder we can see a single folder by default named en-US. If you wanted to create a French Canadian translation for Plato.Discuss you would simply create a copy of en-US and rename this to fr-CA. See a complete list of culture codes.

After renaming the folder open your new fr-CA. You will see 2 JavaScript Object Notation or JSON files by default. These are:-

strings.json

The strings.json file represents all of the user interface text displayed for each module and is the main localisation file you will need to translate.

The strings.json file holds a simple key value pair of strings where the key represents the original English text and the value represents the text to be displayed within the Plato user interface when the original English text is encountered.

You can see an example of the English strings.json file for Plato.Discuss below...

{
  "Strings": [
    {
      "Key": "Post Topic",
      "Value": "Post Topic"
    },
    {
      "Key": "New Post",
      "Value": "New Post"
    },
    {
      "Key": "Discuss",
      "Value": "Discuss"
    }
  ]
}

emails.json

The emails.json file contains any localised emails the module may send. For example for Plato.Discuss users can report topics or replies which trigger an email to staff. You can localise these emails by updating the emails.json file. You can see below the English version of these email templates...

{
  "Emails": [
    {
      "Id": "NewTopicReport",
      "To": "",
      "Cc": "",
      "Bcc": "",
      "From": "",
      "Subject": "[SiteName] - Topic Reported",
      "Message": "Hi {0},\n\nThe topic \"{1}\" has been reported for the reason \"{2}\" by {3} (@{4}). You can review this topic at the link below.\n\n{5}\n\n[SiteName]\n[SiteUrl]"
    },
    {
      "Id": "NewReplyReport",
      "To": "",
      "Cc": "",
      "Bcc": "",
      "From": "",
      "Subject": "[SiteName] - Reply Reported",
      "Message": "Hi {0},\n\nA reply to the topic \"{1}\" has been reported for the reason \"{2}\" by {3} (@{4}). You can review this reply at the link below.\n\n{5}\n\n[SiteName]\n[SiteUrl]"
    }
  ]
}

Setting Your New Language

After you've created the fr-CA folder and modified the emails.json and strings.json files as demonstrated above the next step is to ensure Plato uses emails.json and strings.json files from within your new fr-CA folder.

To achieve this simply visit the general settings page and locate the Language drop down list. You should now see a new fr-CA option available for selection within the Language drop down list. Select fr-CA and save your changes. You can see this below...

NOTE To ensure great performance Plato will cache locale files in-memory. Plato will only traverse localisation files during the initial start-up process. For this reason you may need to recycle your IIS application pool or web site if you create new locale folders whilst Plato is running and these new folder names don't appear within the Language drop down list on the general settings page.

Language Fallback

Taking the example above we went ahead and created a fr-CA locale for Plato.Discuss and set this as our default language via the general settings.

Of course other modules enabled within Plato are not aware of the changes we've just made to our Plato.Discuss module or the introduction of the fr-CA folder. Other modules may not have a fr-CA folder within there Locales folder unless you go ahead and create them. For this reason if Plato cannot locate a locales\fr-CA folder within other modules these modules will fall back to the default English (United States) strings ensuring text and emails still work correctly although in English. When you introduce a fr-CA locale to other modules Plato will detect and use this locale.