Hierarchical TranslateService Proposal

[CodeAndWeb]

Hierarchical TranslateService Proposal

Overview

This proposal defines a hierarchical architecture for ngx-translate that enables child
TranslateService instances to inherit and override translations from their parent services
while maintaining isolation and efficient loading.

Example Application Structure

- TranslateService (AppLevel/Root)
    - TranslateService (Screen1)
        - TranslateService (SubScreen1)
        - TranslateService (SubScreen2)
    - TranslateService (Screen2)

This architecture supports applications with:

• A root translation service at the application level
• Feature-specific translation services (e.g., for lazy-loaded routes like Screen1 and Screen2)
• Component-specific translation services (e.g., SubScreen1 and SubScreen2 within Screen1)

Use Cases:

• Lazy-loaded modules with their own translation files
• Component-specific translations that can override global ones

Desired behaviour

Language Loading Behavior

• Calling use(lang) or setFallbackLang(lang) on any service triggers language loading for all services in the hierarchy (up and down)
• use() and setFallbackLang() observables complete only when all services finish loading (or failed)

Problem: New child services may be instantiated while parent language loading is in progress.

Translation Isolation

Isolation Principles

• Each service maintains its own translation store, separate from parents and siblings
• Services can be destroyed without affecting parent or sibling translations
• Memory management: Child service destruction cleans up its translation store

Benefits

• Modularity: Features can be developed and deployed independently
• Memory efficiency: Unused feature translations can be garbage collected
• Conflict prevention: Child services cannot accidentally break parent translations
• Lazy loading support: Translation files load only when modules are accessed

Translation Resolution

Services resolve translations by checking their own store first, then traversing up the
hierarchy to parent stores. Child and sibling translations are not accessible.

Resolution order for a translation key in SubScreen1:

Option A: Language Priority (Recommended)

1. currentLang of SubScreen1
2. currentLang of Screen1
3. currentLang of AppLevel
4. fallbackLang of SubScreen1
5. fallbackLang of Screen1
6. fallbackLang of AppLevel
7. Trigger MissingTranslationHandler from SubScreen1 (may inherit from parent)

Option B: Scope Priority

1. currentLang of SubScreen1
2. fallbackLang of SubScreen1
3. currentLang of Screen1
4. fallbackLang of Screen1
5. currentLang of AppLevel
6. fallbackLang of AppLevel
7. Trigger MissingTranslationHandler from SubScreen1

Recommendation: Option A provides more intuitive behavior by exhausting all current
language options before falling back to fallback languages. This matches user expectations when switching languages dynamically.

Resolution Example

Translation Files:

AppLevel (currentLang: en):

{
  "a": {
    "app": "lorem"
  },
  "override": "app",
  "common": {
    "save": "Save"
  }
}

Screen1 (currentLang: en):

{
  "a": {
    "screen": "ipsum"
  },
  "override": "screen1",
  "screen1": {
    "title": "Screen 1 Title"
  }
}

Translation Resolution Results (assuming no fallbackLang):

Key	AppLevel Result	Screen1 Result
a.app	"lorem"	"lorem"
a.screen	MissingTranslationHandler	"ipsum"
common.save	"Save"	"Save"
override	"app"	"scrren1"
a	{app: "lorem"}	{screen: "ipsum"}

Important Limitations

No Object Merging: Translation objects from different scopes are not merged.
Calling instant("a") in Screen1 returns {screen: "ipsum"}, not {app: "lorem", screen: "ipsum"}.
Object merging would create unpredictable behavior
and performance issues when dealing with large translation objects or deep nesting.

Observables

onLangChange

Emits after the all services complete loading the language.

Event data: { lang: string }

Breaking change: onLangChange does not provide the translations anymore. This is not
possible due to the hierarchy structure.

onFallbackLangChange

Emits after the all services complete loading the language.

Event data: { lang: string }

Breaking change: onLangChange does not provide the translations anymore. This is not
possible due to the hierarchy structure.

onTranslationChange

Emits when translations are loaded or updated (both: current and fallback language) in
the current service or any higher scoped service.

Event data: { lang: string }

Breaking change: onTranslationChange does not provide the translations anymore. This is not
possible due to the hierarchy structure.

Implementation Details

• TranslateService becomes an abstract class, keeping the shared functionality.
• The TranslateService implementation is split into
  • RootTranslateService
  • ChildTranslateService
• TranslateStore might become partially obsolete.
• TranslatePipe and TranslateDirective must be updated to work with the new Observables.
• extend is restricted to the service itself. Maybe is even obsolete and can be removed?

RootTranslateService

• Maintaining the language and fallbackLanguage settings
• Emitting onLangChange and onTranslationChange events
• Triggering loading in the child services

ChildTranslateService

• Forwards relevant calls to the parent service
  • use(lang)
  • setFallbackLang(lang)
• Handles hierarchy lookup for translations
• Handles local storage for translations

Related: #1585