Page tree
Skip to end of metadata
Go to start of metadata

This page lists high-level proposals and decisions regarding i18n improvements, from various perspectives.




We agreed to the following ranking of i18n improvements:

  1. (tick) i18n in light modules
    • There is consensus to start supporting our existing i18n–as is–within light modules.
    • Will consist of an i18n directory inside the traditional light-module structure.
  2. Minor amendments to existing key generators
    • As it became clear bigger improvements would require more investment, we agreed to a minimal set of changes
    • This minimal set of changes is proposed by Roman Kovařík on the following page: Minimal required changes
    • Participants have a look at them to vote/unvote if there is any objection; they can then be scheduled within the next sprints.
  3. Key generators documentation / reference
    • Most people use the most specific keys, because this is what our UI shows when no translation was found
    • We believe this can be mitigated by documenting our existing key generators properly to advocate for simpler keys, where applicable
  4. Revise tooling
    • As in point #3, we also seek for options to emphasize usage of simpler keys, and make working with keys more intuitive, via better tooling
    • One debated proposal is to change the missing translation fallback to show the shortest, or "rightest" key.
  5. General standardization and new features
    • We defer all bigger improvements regarding key generators
    • e.g. standardized/consistent patterns, pluralization, specialization, or even deprecation mechanism for keys
    • See I18n keys consistency - work document for more details


The additional section below, about the original proposal, may now be moved or archived.


Original proposal

(plus) New suggested key

(thumbs down) Key suggested for deprecation

(tick) old key which is consistent and does't require changes

(question) To be discussed


(plus) "apps.test-app.label", (philip+, espen+)
(thumbs down) "", //we currently add for every key which ends with label automatically another key without label suffix. This unnecessary increases number of keys in memory. We should always specify if it's label/description/icon from my point of view. Adding the label suffix is not a big deal.
(thumbs down) ""

App launcher group

(plus) "appLauncherLayout.groups.groupName.label", //you can immediately identify in an i18n file that it's a group name (compared to the old keys below), moreover appLauncherLayout is the name of the app launcher configuration node

(mika+-, topher+-, philip+-, espen-)

(thumbs down) "app-launcher.groupName.label",
(thumbs down) "app-launcher.groupName"

Actionbar sections

 //new suggested keys respect the path in configuration:

(plus) "apps.test-app.subApps.test-subapp.actionbar.sections.test-section.label",

(plus) "subApps.test-subapp.actionbar.sections.test-section.label", 

(plus) "actionbar.sections.test-section.label", 


(thumbs down) "test-app.test-subapp.actionbar.sections.test-section.label", 

(thumbs down) "test-app.test-subapp.actionbar.test-section.label", 
(thumbs down) "test-app.actionbar.sections.test-section.label",
(thumbs down) "test-app.actionbar.test-section.label",

//having the same key with/wo label suffix unnecessary increases number of keys in memory:

(thumbs down) "test-app.test-subapp.actionbar.sections.test-section",  

(thumbs down) "test-app.test-subapp.actionbar.test-section", 

(thumbs down) "test-app.actionbar.sections.test-section", 
(thumbs down) "test-app.actionbar.test-section"


New suggested keys:

(plus) "apps.myapp.subApps.browser.actions.myaction.label",
(plus) "subApps.browser.actions.myaction.label",

(tick) "actions.myaction.label",

Currently supported keys:

(question) "myapp.browser.actions.myaction.label", //short key, doesn't respect configuration path but is shorter

 //having the same key with/wo label suffix unnecessary increases number of keys in memory:
(thumbs down) "myapp.browser.actions.myaction",
(thumbs down) "actions.myaction"


New suggested keys:

(question) "apps.<app>.subApps.<subapp>.workbench.contentViews.<view-name>.columns.<column-name>.label",
(question) "subApps.<subapp>.workbench.contentViews.<view-name>.columns.<column-name>.label",
(question) "workbench.contentViews.<view-name>.columns.<column-name>.label",

(tick) "columns.<column-name>.label",  //we could probably support this one, if no objections

vs currently supported keys:

(question) "<app>.<subapp>.views.<column-name>.label",

(question) "<app>.views.<view-type>.<column-name>.label",

(question) "<app>.<subapp>.views.<view-type>.<column-name>.label",

(question) "<app>.views.<column-name>.label",

(question) "views.<view-type>.<column-name>.label",

(question) "views.<column-name>.label",

Pretty hard to remember, isn't it? (big grin) Also notice <view-type>. This is tree/list and it doesn't matter how is the view called in config although all the other parts are always the node names in JCR (yaml). 

//having the same keys with/wo label suffix unnecessary increases number of keys in memory:

(thumbs down) "<app>.<subapp>.views.<view-type>.<column-name>",

(thumbs down) "<app>.<subapp>.views.<column-name>",

(thumbs down) "<app>.views.<view-type>.<column-name>",

(thumbs down) "<app>.views.<column-name>",

(thumbs down) "views.<view-type>.<column-name>",
(thumbs down) "views.<column-name>"



New suggested keys:

(plus) "test-module.dialogs.testFolder.testDialog.label",
(plus) "dialogs.testFolder.testDialog.label", //this is "must have". We currently cannot use module-independent translations

(question) "dialogs.testDialog.label",

//currently supported keys:
(thumbs down) "test-module.testFolder.testDialog.label",
(thumbs down) "test-module.testFolder.testDialog" //having the same keys with/wo label suffix unnecessary increases number of keys in memory


New suggested keys:

(plus) "test-module.dialogs.testFolder.testDialog.form.tabs.testTab.label",
(plus) "dialogs.testFolder.testDialog.form.tabs.testTab.label",
(plus) "form.tabs.testTab.label",

//currently supported keys:
(question) "test-module.testFolder.testDialog.testTab.label", Do we still want to have this one? It's shorter but not a big difference and it doesn't respect configuration path.
(thumbs down) "test-module.testFolder.testDialog.testTab",  //having the same keys with/wo label suffix unnecessary increases number of keys in memory
(thumbs down) "testTab.label", //That's pretty dangerous since it's too short and without a type prefix. How you can possibly know where it belongs by looking in the translation file? Is it for template/dialog/app?
(thumbs down) "testTab"


New suggested keys:

(plus) "test-module.dialogs.testFolder.testDialog.form.tabs.testTab.fields.mgnl-testField.label",
(question) "dialogs.testFolder.testDialog.form.tabs.testTab.fields.mgnl-testField.label",
(question) "form.tabs.testTab.fields.mgnl-testField.label",

(tick) "fields.mgnl-testField.label" //we might want to have generic translation for all fields with this name (fallback)

//currently supported keys:
(question) "test-module.testFolder.testDialog.testTab.mgnl-testField.label", //vs "test-module.dialogs.testFolder.testDialog.form.tabs.testTab.fields.mgnl-testField.label",

(question) "test-module.testFolder.testDialog.mgnl-testField.label",

(question) "testDialog.testTab.mgnl-testField.label",

(question) "testTab.mgnl-testField.label", //vs "form.tabs.testTab.fields.mgnl-testField.label",

(question) "testDialog.mgnl-testField.label",

//having the same keys with/wo label suffix unnecessary increases number of keys in memory:

(thumbs down) "test-module.testFolder.testDialog.testTab.mgnl-testField",

(thumbs down) "test-module.testFolder.testDialog.mgnl-testField",

(thumbs down) "testDialog.testTab.mgnl-testField",

(thumbs down) "testDialog.mgnl-testField",

(thumbs down) "testTab.mgnl-testField",


New suggested keys:

(tick) <parentFieldI18nKey>validators.emailValidator.errorMessage //respects configuration path

(tick) validators.emailValidator.errorMessage //respects configuration path

//currently supported keys:

(thumbs down) <parentFieldI18nKey>validation.errorMessage //no information about validator, just field definition



  • No labels


  1. Page with keys using <> syntax and showing the missing specifiers with strikethroughs:

    I18n keys - with strikethroughs

  2. Introductory Notes from meeting on the 29th of February.

    Christopher Zimmermann

    • Cannot introduce migrations
    • Is what we have so bad - do we need to make these changes now?

    Mikaël Geljić

    • Find current patterns.

    • Probably too overly flexible.

    • Current ones are similar but not the same.

    • Pluralization

    • Define the future direction

    • Proper deprecation

    • Try harder - improve the UI tooling

    Philip Mundt

    • Flag for deprecation

    • Recently a lot adjustments

    • Proper deprecation

    • Add some keys to make more consistant

    • Tooling improvements

    Espen Jervidalo

    • Opportunity to cleanup.

    • Think about this flag.

    • Maybe let customers add keyGenerators.

    • Dissallow deprecated keys on light modules

    Roman Kovařík

    • Why now

      • Recently implemnt new i18n for templates

    • Hard to log if people are using deprecated keys.

    • Logging - maybe in 5.5

    • Document only the new keys.

    • Plurals - new major version

    • Fix bad keys for sure.

    • THink how to deprecate