Translation section: structural, API, and editing UX improvements

[rsoeteman]

Translation section: structural, API, and editing UX improvements

Summary

The current Dictionary/Translation section has a flat key structure, no translation API, and a plain-text editing experience. This discussion proposes structural, API, and editor improvements, plus a V2 idea for per-site overrides.

Current behaviour

Dictionary keys need to be unique so we need to do some hacks in our solution, for example:

• App.News.Header
• App.News.ReadMore
• App.Title
• Website.News.Header
• Wesbite.News.ReadMore
• Website.Title

Proposed structure

Instead of flat, duplicated key paths, keys should be organised under shared parent nodes with common child nodes underneath, for example:

• App
  • News
    • Header
  • Title
• Website
  • News
    • Header
  • Title

Much better UX in the tree

Missing: Translation API

There is currently no dedicated Translation API exposing an I18N-style spec built from this structure. The API should output composed, dot-notation keys derived from the tree, for example:

{
  "app.news.header": "News",
  "app.news.readMore": "Read more",
  "app.title": "welcome",
  "website.news.header": "Our awesome news!",
  "website.title": "Welcome on out awesome site",
  "wesbite.news.readMore": "Read more"
}

Custom one created:

There is already a different discussion for this #15214

Editor UX

The current editing experience for a dictionary item is a plain text box. This should support:

• Markdown formatting
• Parameter placeholders that can be combined with the markdown content (e.g. inserting a name or count into a translated string)

V2 idea: per-site overrides

For a more complete solution, it should be possible to localize or override a shared translation key on a per-website (or per-start-node) basis. For example, a key used across nine websites could have its value overridden for a single specific website or start node, without affecting the shared default value used everywhere else.

[mistyn8]

I always wondered why this didn't at least follow the create Section and add Keys (all be it flat) to mirror localizations in packages.
That could also then allow for easy overrides of the core localizations, or easy additions?

And if it needed to be flat, at least if you create keys like app.news.header the tree would show app > news > header as a nested item, even if the backing data is dot notation.
Or indeed look at the camel case notation of the existing core keys? (though chooseWhereToImport wouldn't quite get the intention)

We also have localizations in packages that follow camel+snake this.#localize.term('general_close') or in manifests

"meta": {
        "label": "#welcomeDashboard_label", 
        "pathname": "welcome-dashboard"
      },

I guess my comment is more about overarching consistency?

A nested I18N-style spec for the api would be prefered?

It avoids key collision issues: If a dictionary key itself happens to contain a dot (which can happen with user-generated dictionary keys in CMS platforms like Umbraco), flat dot-notation breaks parsing or forces awkward escaping. Nested objects completely sidestep this.

[rsoeteman]

You are right that might be better indeed, my structure was based on an agreement with front-end devs what they could use. One question in your JSON how would you set a value for "meta" if some-one added a value there as well?

[mistyn8]

Not sure I understand the question,, the meta json snippet there was just to indicate that in a package manifest we access localisations as #welcomeDashboard_label #{SECTION}_{KEYNAME} ?

[DynamicDave]

I completely agree with you, Richard. Ideally, you should be able to create folders alongside keys — something I’ve also been missing for years.

The translation API could then return the data as a tree structure. Something like this:

[{
    "app": [
        "news": [
            "header": [
                "en": "News",
                "nl": "Nieuws",
            ],
            "readMore": [
                "en": "Read more",
                "nl": "Lees verder",
            ]
        ]
    ]
}]

And wouldn't it be absolutely fantastic to have a "translate all empty fields" button somewhere? I think that could be nicely combined with Umbraco.AI.

ps. great talk on headless last Tuesday!

[ravimotha42]

Hmm some interesting things to think about .. I suppose the issue that most will think worry about it effficinency when these things are sent to an external agency to translate and import and how that might effect what you are thinking

I love the idea of per site so global
Keys over written by local

I am less convinced by the need for mark down id say mark down is v3 not a immediate need

[rsoeteman]

Excellent thought about import/export Ravi and Dave as well since AI will probably be the thing to used the most here. Not sure why one would pay an external company these days for translations of mostly labels? I do use Markdown in every project by the way :-) Funny how every project can be completely different in terms of requirements

[melvinvanrookhuizen]

@DynamicDave yes exactly, we have ai fixing and sorting the label messy bits including translation itself. But still, a solid structure is been an issue for years and needs to be fixed.