...

Implementation

Introducing a couple of concepts. The basic API will be in its own module in magnolia_main; it doesn't need to be in core, and will maybe not even depend on it. It could even be outside of magnolia_main if there is no dependency to core, but we currently lack a good location for such modules 

Module and package

magnolia-i18n in magnolia_main would contain the API and some implementation. Key generators etc would live near their counterparts (i.e in _ui mostly)

I would simply use info.magnolia.i18n as a package name. However, if this ends up only being usable within the context of magnolia_ui, I would move it there instead of _main, and reflect that in the module and package names.

API

• @I18nable annotation. "Internationalizable": marks any object as a candidate for translations. Used on interfaces/classes such as FieldDefinition. Is inherited.
• @I18nText annotation. Marks a String as to be translated.
• I18nKeyGenerator<T> interface. Implementations generate translation keys for <T>.

Implementation "details"

try {
   ... something that fails ...
} catch (SomeException e) {
   uiComponent.alert(e.getMessage());
} 

try {
   ... something that fails ...
} catch (SomeException e) {
   // if there is added value: log.error("sumfin happened: {}", e.getMessage(), e);
   // don't feel forced to bloat the logs, though.
 
   // if this is something the *user* should be informed about, and *can* do something about:
   uiComponent.alert(i18n.getMessage(e));
 
   // but really, is it ? Can a user do anything about a JCR Exception ?
   throw new RuntimeException(e); // did you need to catch it in the first place ?
} 

Implementation

Introducing a couple of concepts. The basic API will be in its own module in magnolia_main; it doesn't need to be in core, and will maybe not even depend on it. It could even be outside of magnolia_main if there is no dependency to core, but we currently lack a good location for such modules 

Module and package

magnolia-i18n in magnolia_main contains the API and the underlying. Key generators live near their counterparts. (i.e in _ui mostly)

The main package is info.magnolia.i18nsystem as a package name.

API

• @I18nable annotation. "Internationalizable": marks any object as a candidate for translations. Used on interfaces/classes such as FieldDefinition. Is inherited.
• @I18nText annotation. Marks a String as to be translated.
• I18nKeyGenerator<T> interface. Implementations generate translation keys for <T>.
• TranslationService
• I18nizer. Transforms/decorate a given object and internationalizes it.
• I18nParentable. This is an interface that allows setting a "parent" on an object. This interface should not be used by client code.

Implementation "details"

• Tried to implement a Guice module that would do this transparently; also tried to implement this at Node2Bean level. Neither worked - didn't find a way to "swap" instances in Guice (i.e replace bean created by n2b by a proxy)
• I18nizer thus needs to be invoked explicitely. We have one implementation based on ProxyToys which creates a proxy. It intercepts methods that return other @I18nable objects (by returning one instance, a collection, or a map where value are of an annotated type) and decorate those. Those proxies in turn intercept
• A Guice module which intercepts the creation of objects annotated with @I18nable and proxies them
• Said proxy intercepts method calls annotated with @I18nText and returns translated values by delegating to i18nKeyGenerator and TranslatorService.
• I18nizer also "injects" the I18nParentable interface and sets the parent object while intercepting calls.

Update tools and tasks

To migrate our own modules, we can write a tool which:

• Starts up a repo and a specific (or several) component managers
• Load up a translation file we want to migrate (or all its language counter parts)
• Imports a bootstrap file we want to migrate
• This should instantiate a whole bunch of forms etc
• Go through these one by one
  
  • Go through each @I18nText property of the object
    property of the object
    
    • Does it correspond to a key currently existing in the translation file ?
      
      • yes: replace key in translation file by deduced key, remove property from jcr
      • no: add key in translation file
    • If it's a key but it doesn't have an existing translation
      
      • add deduced key to translation file (instead of configured key), remove property from jcr
    • If it's not a key, i.e current configuration has an "hardcoded" text
      
      • warn, blow up, panic, ...?
      • add deduced key to translation file (instead of configured key)
      Does it correspond to a key currently existing in the translation file ?
      
      • yes: replace key in translation file by deduced key, remove property from jcr
      • no: add key in translation file
    • If it's a key but it doesn't have an existing translation
      
      • add deduced key to translation file (instead of configured key), remove property from jcr
    • If it's not a key, i.e current configuration has an "hardcoded" text
      
      • warn, blow up, panic, ...?
      • add deduced key to translation file (instead of configured key), remove property from jcr
  • Track unused keys in translation files
  • Track possible duplicates
• Re-export file to replace bootstrap file
• Re-export translation file(s)

The same tool could maybe be used to generate update tasks, or generate some sort of config/mapping file passed to a specific update task: it will only need a list of properties to be removed from nodes, with their original value so that we don't remove a property that's been modified by a user.

Message bundles for non-english texts

Bundle languages in separate jars

• • Track unused keys in translation files
  • Track possible duplicates
• Re-export file to replace bootstrap file
• Re-export translation file(s)

The same tool could maybe be used to generate update tasks, or generate some sort of config/mapping file passed to a specific update task: it will only need a list of properties to be removed from nodes, with their original value so that we don't remove a property that's been modified by a user.

Message bundles for non-english texts

Bundle languages in separate jars

• english/master language still bundled with each module, other languages bundled in 1 jar (1 jar per language, containing translations for many modules)
  • on git, this would be, for example languages/french.git - which would contain N files.
  • These language bundles could be a module. They could thus be versioned, and have dependencies. Dependencies to module they translate would be marked as optional, but we would be able to maintain some sort of version-compatilbility between modules and translations - granted, that wouldn't be super simple to manage - where, for example, we'd update a dependency when keys have been added/removed from that dependency.
  english/master language still bundled with each module, other languages bundled in 1 jar (1 jar per language, containing translations for many modules)
• maintenance is somewhat easier
• but at the same time we might get "dependency" issues when modules add/remove keys
• if we have tools for migration/validation of existing translations, the same tools could be used, perhaps as a maven plugin or sthg.
  
  • such a tool could potentially help enforcing compatibility between versions (i.e keep a key that was removed in version X+1 of module M)
• Need some sort of version handling - keep keys for older versions, add keys for newer ones ...
  
  • Chain (overlay) current translation file with older ones ?

...

• Enable inline translations within a dialog
  
  • I'm not sure the current proposal would work to enable inline translations. It'd be nice for translators to have at least a hint of what the key used for a specific item is. And if we somehow have elements explicitly use the KeyGenerator and other API methods for this, we might as well get rid of the proxy magic and use consistently... 
• Review process for in-house maintained translations as well as for contributed ones (currently relying on Google spreadsheet)
  
  • Have a Magnolia-hosted (or SaaS) tool to replace the google spreadsheet
    
    • some rules like "a translation needs to be validated by 2 other persons to be applied", "once applied it can't be changed directly - only via a 'request'", ...
    • could have a "MessagesManager" impl that fetches translations from this service
    • candidates so far: Transifex (am in contact with CEO Dimitris Glezos, who seems eager to help), Crowdin, WebTranslateIt, ... probably others.

Roadmap

• 5.1 : system in place, translations migrated for AdminCentral and most modules (DAM, STK, ...)
  • Module updates can be postponed
• ? : extract languages other than english into language-based bundles - language-based bundles - needs a separate concept.
• ? : review processes for translating Magnolia, both internally and externally. Get contributions. With language files extracted from their modules, it might be easier. - needs a separate concept.

Status

...

Main issues:

• Jira
  server Magnolia - Issue tracker key MAGNOLIA-5268

• Jira
  server Magnolia - Issue tracker key MGNLUI-1826

 Validate Concepts

 Validate Roadmap

 API

 Finalize module name, location, and package name.

 Implementation details (proxy, Guice module, ...)

 Parental relationships

 How does this work with Multi/composite fields

 Check things like info.magnolia.ui.form.field.definition.DateFieldDefinition#getDateFormat - might actually work with @I18nText or another annotation

 Is there a conflict with merged objects ? (i.e template definitions merged with site def prototype - but also look at other merge cases!!)

 An i18Basename could also be defined in site definitions (for in-template translations) - does this work ?

 Clarify what to be with i18nBasename properties - the current tendency is to get rid of them. Adapt update tools as needed.

 Replace MessagesManager with a cleaner impl

 Migration and updates

 While this implementation has focused on definition objects, (some) "live" objects already know their parent (see for example 

Status

Main issues:

• Jira
  server Magnolia - Issue tracker key MAGNOLIA-5268

• Jira
  server Magnolia - Issue tracker key MGNLUI-1826

 Validate Concepts

 Validate Roadmap

 API

 Finalize module name, location, and package name.

 Implementation details (proxy, Guice module, ...)

 Parental relationships

 How does this work with Multi/composite fields

 Check things like info.magnolia.ui.form.field.definition.DateFieldDefinition#getDateFormat - might actually work with @I18nText or another annotation

 Is there a conflict with merged objects ? (i.e template definitions merged with site def prototype - but also look at other merge cases!!)

 An i18Basename could also be defined in site definitions (for in-template translations) - does this work ?

 Clarify what to be with i18nBasename properties - the current tendency is to get rid of them. Adapt update tools as needed.

 Replace MessagesManager with a cleaner impl

 Migration and updates

Topics to validate or research

...

FormItem) - validate and justify the choice to decorate definition objects.

Known bugs or problems:

• Jira
  server Magnolia - Issue tracker key MAGNOLIA-5315

• Jira
  server Magnolia - Issue tracker key MAGNOLIA-5317

• we have no proper way, yet to i18n-ize GWT- / Vaadin-Client-Classes; neither info.magnolia.cms.i18n.MessagesUtil nore the i18n-toolz can be applied on those client-classes

Topics to validate or research

...

• A form can be used in different contexts. It should be translatable according to context.
  
  • TBD: details, examples
  Where do we pass the user context (i.e locale)
  should be translatable according to context.
  
  • TBD: details, examples
  • Can we set it at injection time ?
  • Do we add an interface for retrieving the locale-to-use ? (Which UiContext could implement for example)

Existing uses and inconsistencies to fix for 5.1

•  info.magnolia.ui.form.AbstractFormItem#getMessages - should not be public
  
  • Is broken: doesn't use the user locale afaict.
•  info.magnolia.ui.form.AbstractFormItem#getMessage - should not be public
•  AbstractFormItem defines a semi-arbitrary message bundles chain (see AbstractFormItem#UI_BASENAMES)
•  Definition objects( TabDefinition, etc) have an i18nBasename property, which is very redundant with that of the "runtimes" objects ( FormTab, ...). Usage seems consistent ( return definition.getI18nBasename();) but I don't know why this isn't implemented in info.magnolia.ui.form.AbstractFormItem.
•  Definition objects don't have a common interface. If they did, we could move i18nBasename and label in there. OTOH, some of these objects have more than 1 item to translate (label and description, for example).
•  view.addFormSection(tab.getMessage(tabDefinition.getLabel()), tab.getContainer()); ...translates the message from the tab and passes it translated before it's actually "displayed". (while the method argument is called tabName not tabLabel - but that passed object becomes an argument called caption later down the stack) - the below would make this sort of code much more explicit. You pass an object meant to be a label. You translate it explicitly - most likely at the last possible moment. Or we even extend Vaadin component so that they know about I18nItem.
•  getI18nBasename is defined in too many places. It's inconsistent and unintuitive. Why the redundancy between info.magnolia.ui.dialog.Dialog#getI18nBasename and info.magnolia.ui.dialog.definition.DialogDefinition#getI18nBasename for example ?
•  info.magnolia.ui.form.FormBuilder#buildForm still does "StringUtils.isNotBlank(description)", but since this is now decorated, it will never be blank or null. See 

  Jira
  server Magnolia - Issue tracker key MAGNOLIA-5315

   though.

Suggested key patterns

The below is a rough outline. The 3 goals below are somewhat hard to reach all at once.

...

<dialog-name>.actions.<action-name>

<app-id>.label

<app-id>.icon # because the icon might have to be localized

<app-id>.description # because a mouse-over title of the app might be interesting ?

app-launcher.<app-group-name>.label # we use the app-launcher prefix, as if app-launcher was an app (which we should consider considering, I suppose)

<module-name>.<template-name>.title # I think "title" is what we've been using in 4.x - we could use label for consistency, or simply name

<module-name>.<template-name> # same as above

<module-name>.<template-name>.desc # Useful in template selector

<module-name>.<component-name>.title # see remark above

<module-name>.<component-name>

<module-name>.<component-name>.desc

<app-id>.<sub-app-name>.views.<view-name>.<column-name>

...