SocialStack - User contributions [en-gb]

Translations

2024-12-11T14:15:40Z

2A02:C7C:C40C:2600:8C18:EA9F:289C:239D: /* Embedding translations into UI Modules */

= 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:

<syntaxhighlight lang="js">
`Hello, world!`

`Hello ${username}`
</syntaxhighlight>

It's important to use variables inside your [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals 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:

<syntaxhighlight lang="js">
import Html from 'UI/Html';

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

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.

<syntaxhighlight lang="js">
// 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`
</syntaxhighlight>

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'.

<syntaxhighlight lang="json">
{
"Feed" : "Attività",
"News" : "Notizia"
}
</syntaxhighlight>

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

<syntaxhighlight lang="json">
{
"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"
]
}
</syntaxhighlight>

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
<syntaxhighlight>
/v1/translation/prepopulate
</syntaxhighlight>

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
<syntaxhighlight>
/v1/{entityTypeName}/list.pot
</syntaxhighlight>

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
<syntaxhighlight>
/v1/translation/potfiles
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
socialstack install Admin/Translation/Upload
</syntaxhighlight>

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

<syntaxhighlight>
/en-admin/translation/upload
</syntaxhighlight>

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

Architecture

2024-12-11T14:00:06Z

2A02:C7C:C40C:2600:8C18:EA9F:289C:239D: /* Consistency */

SocialStack is primarily a fully open source dotnet core 6 API. By default it comes with a React frontend installed which can also be simply ignored or removed if you wish to use it headless instead.

= Founding Pillars =

SocialStack, like really any designed system, has foundational design pillars that it and all projects on it are built to follow.

== Simplicity ==

First and foremost, keep it simple. SocialStack is frequently used in fast iterating projects which often also have high performance requirements too. Dozens of layers of boilerplate are precisely what we want to eliminate at all times.

== Consistency ==

A handful of universally followed patterns help a team naturally produce compatible code, even if it is in different projects. There is nothing stating that you have to use SocialStack's automated database entities in your new code, but doing so means you get a significant amount of features for free just simply because your code is fitting in with the norm. Better yet, the SocialStack generate command will spawn a new module which is perfectly consistent with every other module in a single line:

<syntaxhighlight lang="bash">
socialstack generate Api/VehicleBrands
socialstack generate UI/Vehicle/Brand/View
</syntaxhighlight>

== Modularity ==

Grouping things by feature rather than some abstract functional type makes following and testing the code substantially easier. Working with something to do with Users? It's probably in a folder called Users.

== Generic and reusable ==

Configuration such as feature flags, event based design, partial classes and avoiding project specific namespacing are all essential to how code can be easily reused between projects and within a project. Public MIT licensed reusable components are installable using the [https://www.npmjs.com/package/socialstack SocialStack command line tools] and ultimately originate from [https://github.com/socialstack-core/modules this GitHub repository].

Architecture

2024-12-11T13:57:56Z

2A02:C7C:C40C:2600:8C18:EA9F:289C:239D:

SocialStack is primarily a fully open source dotnet core 6 API. By default it comes with a React frontend installed which can also be simply ignored or removed if you wish to use it headless instead.

= Founding Pillars =

SocialStack, like really any designed system, has foundational design pillars that it and all projects on it are built to follow.

== Simplicity ==

First and foremost, keep it simple. SocialStack is frequently used in fast iterating projects which often also have high performance requirements too. Dozens of layers of boilerplate are precisely what we want to eliminate at all times.

== Consistency ==

A handful of universally followed patterns help a team naturally produce compatible code, even if it is in different projects. There is nothing stating that you have to use SocialStack's automated database entities in your new code, but doing so means you get a significant amount of features for free just simply because your code is fitting in with the norm.

== Modularity ==

Grouping things by feature rather than some abstract functional type makes following and testing the code substantially easier. Working with something to do with Users? It's probably in a folder called Users.

== Generic and reusable ==

Configuration such as feature flags, event based design, partial classes and avoiding project specific namespacing are all essential to how code can be easily reused between projects and within a project. Public MIT licensed reusable components are installable using the [https://www.npmjs.com/package/socialstack SocialStack command line tools] and ultimately originate from [https://github.com/socialstack-core/modules this GitHub repository].