search

msupply-foundation / open-msupply

Open mSupply represents our most recent advancement in the Logistics Management Information System (LMIS), expanding on more than two decades of development inherited from the well-established legacy of the original mSupply.
https://msupply.foundation/open-msupply/
Other
19 stars 12 forks source link

Organise translation namespaces #4060

Open mark-prins opened 1 month ago

mark-prins commented 1 month ago

The suggestion

The current organisation of translation namespaces might not be entirely fit for purpose and it would be good to review how it is working and if we can improve.

The original intention was to divide translation strings into functional areas, so that the app would only need to download strings for the area that the user is working in, reducing the overall download size. I would still strongly recommend splitting the strings into namespaces, and I also prefer having the translation keys prefixed in a way to divide them e.g. button.save settings.label-printing

However.. given that the JSON files are cached, perhaps the huge initial download isn't critical? In which case we could split across tasks e.g.

buttons.json errors.json

even though this would require editing multiple translation files while working on a feature.

Here are the current namespaces:

namespace description
app Application-wide strings such as menu items and keyboard shortcuts
common Strings which are used in more that one area and strings which are called from the common package by shared components
dashboard Dashboard-specific strings
distribution Anything used solely in the distribution area: Outbound shipments, Requisitions &c.
inventory Inventory only strings
replenishment Replenishment only strings
catalogue Catalogue only strings
dispensary Dispensary only strings
programs Programs specific: the HIV program work for PNG
coldchain All things coldchain, including the assets module now
plugin A separate space for plugin specific strings
manage The new central server-only administration aspects; for centrally managed things e.g. names for GAPS

Example use case

Why should we invest time in this?

There's possibly a small overhead in developer time with the current split. I have heard complaints, though nothing tangible enough to flesh out this issue. There may also be a small improvement in app responsiveness if we get the split perfect, and conversely, a decrease in performance if we prioritise developer's needs.

A concern would be having a single file, as this would increase the incidence of development conflicts. Splitting by functional areas is a sensible way to remove this risk.

Are there any risks associated with this change?

How much effort is required?

Probably not much 🤷 The development change is minor, perhaps half a day to move strings around. Deciding what to do, that will take days.

Agreed Solution

jmbrunskill commented 3 weeks ago

One problem I have with the breaking down of things into buttons.add-name and label.add-name is that I feel like we get a lot of duplication. Maybe we should have a difference between a button text and label text, I currently don't feel clear on it. I do support this refactor though. Would be nice if we could think about other things too when we're re-doing it, such as duplication for translation.

mark-prins commented 3 weeks ago

to check: does caddy gzip by default? If the JSON files are gz then they'll be much smaller. they're cached too, so the bundle size isn't a big deal.

andreievg commented 3 weeks ago

Triage, maybe the refinement can determine when this is done ? We've had conversation about this area a few times, maybe that should be reflected in the priority

jmbrunskill commented 3 weeks ago

to check: does caddy gzip by default? If the JSON files are gz then they'll be much smaller. they're cached too, so the bundle size isn't a big deal.

Caddy doesn't gzip by default but Actix already does compression. image 7.58KB for current common.json Potentially we'll get better compression % for a bigger file?

(Compression can be turned on via Caddy is needed, but it should just pass through this compression)

mark-prins commented 2 weeks ago

Duplicate of #1266 - and both issues have useful info. Keeping both open for now until we decide on an approach. Just looking at potential file size we currently have a 1,512 translations, so a single file is possible though a little cumbersome.

namespace translations
app 142
catalogue 66
coldchain 183
common 547
dashboard 35
dispensary 99
distribution 150
inventory 119
manage 1
plugin 2
programs 14
replenishment 154
  1512

Note that we have a few scripts to check for unused and missed translations.

Perhaps a 'duplicates' script is possible too? Started looking at li18nt and haven't had success getting that running..

So - to summarise:

Approach Pro Con
Single file LocaleKey type includes all translation keys, it isn't possible to try and translate using namespace a when the translation exists in namespace b Potential for development conflicts
Possible to find duplicates easily if you sort all entries by key GitHub doesn't like displaying large diffs
large single file for clients to download / not possible to split translations by usage area
Unwieldy to work with a large file?
Reorganise namespaces Some people find the current grouping not very logical Potential to increase conflicts
Might have to update large number of translation files when working on a single feature

it might be possible to resolve the type safety if we don't use a big 'ol LocaleKey as we currently do - the question is, do the benefits of splitting translations up justify the cost of the time required?