Translations

Getting Started

Translations can come from a variety of sources, this is meant as a getting started guide to adding and managing translations in social stack

Directly added to the database via the admin panel

You can use the admin panel to add entries manually to any entities which have localised fields, there is also the translation table which holds translatable text from within UI modules.

Embedding translations into UI Modules

To add some translatable text to a module it needs to be wrapped in `` quotes like this:

`Hello, world!`

`Hello ${username}`

It's important to use variables inside your javascript template literals rather than just joining the text together in a specific order because word order varies and sometimes quite a lot. That's even in locales of English for example - "July 19th" (American English) and "19th of July" (British English).

If you would like to add HTML formatting in your text, it can also move around and should therefore just be entirely within your template literal too, like this:

import Html from 'UI/Html';

<Html>{`Hello <b>${username}</b>`}</Html>

Importantly, avoid performing logic inside your template literals. This is because often times such logic doesn't actually translate to other languages anyway and you are effectively asking a translator to write code which they won't and can't do.

// Don't do this! E.g. German translators would have to understand and edit the code itself.
`Shoe${count > 1 ? `s` : ``}`

// Instead, always do your logic outside the literal:
count>1 ? `Shoes` : `Shoe`
// Such that a German translator thus provides `Schuhe` and `Schuh`

Socialstack has built in tools to collect all template literals in your code in order to get them in to e.g. a pot file for translation, as well as then importing them back in to the translation table whereby multiple versions of the .js file are built with the translations directly substituted in. This means all secondary languages obtain the same runtime performance as the primary language (the one that the code was written in).

Default translations for a module (only available when hosted locally/DEV)

You can add default translations into locale.xx.json files as part of UI modules where xx is the locale code, so for example 'it'.

{
	"Feed" : "Attività",
	"News" : "Notizia"
}

These files are processed when the page builder (UIBundle) is run locally to build the core page bundle and inject any translations.

They are used as the default but may be replaced by values from the database translations table, this will only happen locally as when deployed these files will not be available, they can however be loaded into the database for deployment as explained below.

These files allow baseline translations to be stored as part of the module itself and be imported into the database as explained below

Auto generating translation table entries (only available when hosted locally/DEV)

You can use the translation service to auto generate translation values from the application modules, this will locate any translatable elements in the current applications UI modules and add entries into the database, if there are locale.xx.json files for the module then these can also be optionally imported.

This is useful when you have a new project or have created lots of new modules and want to extract the elements for translation.

First you need to update the translation service config as below

{
  "ReformatCanvasElements": false,
  "AutoAddBaseLineTranslations": true,
  "AutoAddTranslationElements": true,
  "AutoAddExcludeModules" : [
        "Admin/Dashboards/Database",
        "Admin/Layouts/MediaCenter",
        "Admin/AutoList",
        "Admin/AutoForm",
        "Admin/CanvasEditor/RichEditor",
        "Admin/Layouts/Dashboard",
        "Admin/Dashboards/Developer",
        "Admin/PermissionGrid",
        "Admin/Dashboards/StressTest"
      ]
}

If AutoAddBaseLineTranslations is true then any locale.xx.json files will be processed and their values added into the translations table.

if AutoAddTranslationElements is true then any translatable items found when parsing the UI modules will be added, you can add exclusions as above to ignore any backend modules for example.

To perform the auto generation, login as an admin user and run the following url

/v1/translation/prepopulate

Any generated messages will be written to stdout

Exporting po files for translation

Once you have your entries in the database you can export a pot file and use it to easily create the localised values for the languages supported by your application

For each table you need to run a request to generate the po file

To perform the auto generation, login as an admin user and run the following url

/v1/{entityTypeName}/list.pot

So for example with the translation table it would be /v1/translation/list.pot

The output file can be opened in a suitable editor such as po edit which can be downloaded from https://poedit.net/

Once translated the generated file can be loaded back into the platform

Importing translated po files

Once we have a translated po file it can be loaded into the platform, there are currently 2 options for this

Mass import of translation files (only available when hosted locally/DEV)

If it is just entries relating to the translation table they can be copied into the /translation folder in the root of the application and loaded using a helper url in the translation service (this may be get extended to other entities as time allows)

copy any po files into the /Translations folder in the root of the solution (you may need to create this)

To perform the load, login as an admin user and run the following url

/v1/translation/potfiles

The progress will get written to stdout

Upload the po files via the admin UI

The alternative is to use the admin panel to upload and process the po files, this is currently the ONLY option for non translation table entries and is useful if you need to update a remote site

You may need to import the admin UI module

socialstack install Admin/Translation/Upload

To perform the import, login as an admin user and load the following page

/en-admin/translation/upload

Enter the name of the entity you are loading (this is a safety check) so for example translation or page

Upload the po file

Click the button to start the process

Once it has completed some stats will be returned showing how may items were updated etc