[MGNLDEMO-212] Move Travel Demo template labels into a separate message bundle Created: 24/Mar/17  Updated: 28/Nov/17  Resolved: 19/May/17

Status: Closed
Project: Magnolia Demo Projects
Component/s: None
Affects Version/s: None
Fix Version/s: 1.1.4

Type: Task Priority: Neutral
Reporter: Antti Hietala Assignee: Robert Šiška
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Relates
duplicate
is duplicated by MGNLDEMO-160 Separate i18n UI messages and templat... Closed
Template:
Acceptance criteria:
Empty
Task DoR:
Empty
Documentation update required:
Yes
Date of First Response:
Sprint: Kromeriz 96
Story Points: 2

 Description   

We have a best practice about template labels:

Create separate message bundles for user interface labels and template labels. Don't store these two groups of text in the same properties files or message bundles. They are aimed at different audiences and have different localization requirements.

But we don't follow our own advice. Let's set a good example and move template labels in the Travel Demo project to a separate message bundle!

Doc update required when completed: In the best practice box, provide a link to the separate template label bundle in Travel Demo code so users can look at the example and follow suit.



 Comments   
Comment by Roman Kovařík [ 10/May/17 ]

We need a precise format of file names, e.g.
<moduleName>.<definitionType>.(<definitionId>).messages.properties?
tours.apps.tours.messages_en.properties (do we want to have every app in the module separate?)
tours.dialogs.messages_en.properties
tours.templates.messages_en.properties
We should probably start with the module name (we can also omit the module name but for searching in an IDE would be better to have it).
Also the messages suffix seems like a remnant from the old i18n, we don't call it messages anymore, maybe rather ...i18n_en.properties?

WDYT, ahietala?

Comment by Mikaël Geljić [ 10/May/17 ]

I would not make it a recommendation to split by def-type.

  • app and dialog translations are both targeted at authors
  • the next thing one could ask is to move i18n files within those module sub-folders (maybe, but rather keep it loose here for now)

Templating keys on the other hand are for visitors—and not even all of them:

  • Template definition translations may be in that same author bundle, e.g. def titles and descriptions.
  • Template script translations should be in a visitor bundle, e.g. "next page", "search", 404 page text.

Re: naming, I couldn't come up with anything clearer than -author/-authoring vs. -visitor; maybe worth asking those who implemented such split in real life?

EDIT: I seem to remember -frontend was an option too. Other keys (the majority) could remain unsuffixed.

Simplifying to the extreme, we don't need an app or module prefix either.

  • tours-messages_en.properties
  • tours-frontend-messages_en.properties
Comment by Christoph Meier [ 10/May/17 ]

Concerning naming:
As Antti mentioned on hipchat, there are some filename recommendations on i18n docs, however, since we already have message bundles per modules, the recommendations are not helpful in this case.

existing file:
module-travel-demo-messages_<locale>.properties
new file proposals
(a) module-travel-demo-messages-template-labels_<locale>.properties
(b) module-travel-demo-template-labels_<locale>.properties
(a) is a really long name, so i would create (b)
=> module-<module-name>-template-labels_<locale>.properties

edit:i have read Mikas proposal above a bit late. Sounds good for me too (actually his naming is more obvious when it comes to the meaning of the file).

Concerning splitting up files:
There was already a long discussion (on hipchat some weeks ago)
Summary:
I just would split when there is really a need for it - having different lang. set for editors and visitors.
But if we wanna showcasing it:
Have a separate bundle for template labels (hardcoded stuff on the template displayed to visitors).
Whether it is required to have separate labels for each app and one for the "rest" of the texts used in the module (if such labels exist) - i don't know.

Comment by Antti Hietala [ 10/May/17 ]

Some points:

  • We recommend to start a message bundle file name with module- or app-. I don't know why. Does the system react to the prefix or is it for the benefit of the human? I would assume that it's easier for a translator if all back-end UI labels are in one file but I don't have hard evidence.
  • The legacy messages suffix is somewhat misleading. Messages (banners, alerts, notifications) is only one group of translatable text that goes into a message bundle. In the same file you also put workbench, column, form, action and button labels because all of them are displayed to authors in the back-end UI. So "messages" doesn't describe the contents of the file very well anymore. I quite like mgeljic's suggestion backend vs. frontend.

Preference:

  • travel-demo-backend_en.properties
  • travel-demo-frontend_en.properties
Comment by Christoph Meier [ 10/May/17 ]

If i remember correctly,
when using the "new" i18n API, bundle file names do not have to be unique among a bundle - but uniqueness is required for the keys among all bundles (being merged into a virtual "super bundle").
So, as long as the file system agrees, everything would work.

The documented recommendations are the outcome of some concept pages from Greg (i would say). We can adapt them.
Personally i "like" to have one bundle per app. if there is one.

But this is
<module-name>-backend_<locale>.properties
<module-name>-frontend_<locale>.properties
definitively a straightforward solution.

Comment by Mikaël Geljić [ 10/May/17 ]

Does the system react to the prefix or is it for the benefit of the human?

Module- or app- prefixes don't matter; even in our own modules we're not fully consistent.

The legacy messages suffix is somewhat misleading.

The messages suffix is more historical than legacy; in past versions (before the M5 new i18n), you would simply put "messages_xx.properties" in your module package and set the base-name accordingly. With the M5 i18n, everything went to the mgnl-i18n directory, the human-friendly differentiator had to become part of the file name. But "messages" was never required there, it just stayed out of unspoken convention.

Happy to keep calling the first token a <module-name>, as it's clear enough also in the context of light modules; then for the rest no need to be overly specific—developers can judge if they need different naming or splitting.

Looks like we have a winner?

Generated at Mon Feb 12 05:17:26 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.