DOCSEARCHbyAlgolia
Submit Docs

Transloco Documentation

repository·master·Indexed 23 days ago

https://github.com/jsverse/transloco

A robust internationalization (i18n) library for Angular applications. Transloco supports runtime language switching, Signal-based APIs, standalone components, lazy loading, and SSR. It includes a rich ecosystem of plugins such as Transloco Locale L10N, Persist Language, and Scoped Libs, as well as support for ICU MessageFormat syntax.

Tokens
25.1K
Snippets
38
Records
184
Agent score
80%

What's inside Transloco

  1. Overview of Transloco features

    master

    Transloco is an internationalization (i18n) library for Angular that allows you to define translations in multiple languages and switch between them at runtime.

    Key capabilities include:

    • Signal-based API: Modern Angular integration.
    • Standalone Support: Fully compatible with standalone components.
    • Lazy Loading: Efficient loading of translation files.
    • SSR Compatibility: Works with Server-Side Rendering.
    • L10N Support: Built-in localization features.
    • Extensibility: A variety of plugins and highly customizable architecture.
    • Developer Tools: Includes Schematics for streamlined setup.

  5. How `provideTranslocoScope` handles multiple scopes

    master

    The provideTranslocoScope helper is used to provide translation scopes to components. When you provide multiple scopes, Transloco uses Angular's dependency injection with the multi: true flag to collect all provided scopes into an array.

    Important Behavior Note: Because provideTranslocoScope uses multi: true, Angular collects all provided scopes in the hierarchy into an array. This affects how different APIs consume these scopes:

    • *transloco directive and transloco pipe: These correctly handle arrays of scopes and use forkJoin to load all of them.
    • selectTranslate() and Signal API (translateSignal): These currently receive the array of scopes but have historically struggled to pick the correct scope. In current versions, they may pick the first scope ([0]) or the last scope ([lang.length - 1]) to approximate Angular's "closest provider wins" behavior. To ensure the component's own scope is used, ensure the scope is provided at the component level.

  6. Migrate to Transloco v3: Configuration and Dependency Updates

    master

    Transloco v3 updated dependencies and changed how configuration is handled. This version requires @angular/core v12 or higher.

    Configuration Changes

    • Scope Mapping: The scopeMapping property has been removed from TranslocoConfig. Instead, define the alias directly on the scope provider.
    • Removed Functions: provideTranslocoConfig has been removed.

    API Changes

    • LoadedEvent: The lang property has been removed from LoadedEvent.
    • Testing: TranslocoTestingModule no longer has the withLangs method; use forRoot instead.
    • Messageformat: Upgraded to @messageformat/core v3.0.0. Messageformat compiled messages are now cached by default.

  7. Migrate to Transloco v8: Utility Functions and Schematics

    master

    Transloco v8 introduced breaking changes regarding utility functions and Angular schematics.

    Utility Functions

    Many utility functions have been removed from @jsverse/transloco:

    • Moved to @jsverse/utils: isFunction(), isString(), isNumber(), isObject(), isNil(), isDefined(), size(), isEmpty(), coerceArray(), toCamelCase(), and toNumber().
    • Removed (Internal only): shouldListenToLangChanges(), listenOrNotOperator(), resolveInlineLoader(), getEventPayload(), isScopeObject(), hasInlineLoader(), getPipeValue(), getLangFromScope(), getScopeFromLang(), flatten(), and unflatten().

    Angular Schematics Migration

    The main @jsverse/transloco package now only includes the ng-add schematic. All other schematics have been moved to @jsverse/transloco-schematics.

    To restore functionality for component, scope, or migration generation, install the new package:

    npm install @jsverse/transloco-schematics --save-dev

    Example usage for scope generation:

    ng generate @jsverse/transloco-schematics:scope my-scope
    npm install @jsverse/transloco-schematics --save-dev
ng generate @jsverse/transloco-schematics:scope my-scope

  8. Migrate to the @jsverse scope

    master
    The Transloco packages have moved from their previous scope to the @jsverse scope. To access the latest features and ensure compatibility, you must update your project dependencies to use the new @jsverse/transloco package names.

  9. Migrate to Transloco v5: Standalone and Provider-based API

    master

    Transloco v5 moved to a standalone architecture and replaced Module-based configuration with provider functions. This version requires @angular/core v16 or higher.

    Key Changes

    • Standalone: Pipes, directives, and components are now standalone.
    • Providers: forRoot() has been removed from modules. Use the following provider functions instead:
      • For Transloco: provideTransloco()
      • For Locale: provideTranslocoLocale()
      • For Messageformat: provideTranslocoMessageformat()
      • For Persist Lang: provideTranslocoPersistLang()
      • For Persist Translations: provideTranslocoPersistTranslations()
      • For Preload Langs: provideTranslocoPreloadLangs()
    • Tokens: Injection tokens are now prefixed with TRANSLOCO_.
    • Scope: TRANSLOCO_SCOPE is now always provided as a multi-token.

  10. Migrate to Transloco v2: Structural Directive and API Updates

    master

    Transloco v2 introduced significant changes to the structural directive and service methods.

    Structural Directive Usage

    The structural directive is now a memoized function. Instead of using the pipe syntax for everything, use the function syntax:

    <!-- Before -->
{{ t.a.b }} {{ t.hello }} {{ t.someKey | translocoParams: { value: 'value' } }}

<!-- After -->
{{ t('a.b') }} {{ t('hello') }} {{ t('someKey', { value: 'value' }) }}

    Service API

    • Object Querying: To query an object instead of a key, use the new dedicated methods:
      • service.translateObject('a.b', params)
      • service.selectTranslateObject('a.b', params)
    • Callback Support: Removed callback parameter support from translate().

    Configuration

    • Required Fields: It is now required to set availableLangs in your configuration.
    • Renamed Flag: listenToLangChange was renamed to reRenderOnLangChange for clarity.
    {
  provide: TRANSLOCO_CONFIG,
  useValue: {
    availableLangs: ['en', 'es'],
    reRenderOnLangChange: true
  }
}
    {{ t('a.b') }} {{ t('hello') }} {{ t('someKey', { value: 'value' }) }}

  11. Migrate to Transloco v7: Scoped Packages and API Changes

    master

    Transloco v7 involved a major migration to the @jsverse scope and several API updates.

    Package Scoping

    All Transloco packages were moved to the @jsverse scope. This includes:

    • @jsverse/transloco
    • @jsverse/transloco-messageformat
    • @jsverse/transloco-locale
    • @jsverse/transloco-optimize
    • @jsverse/transloco-persist-lang
    • @jsverse/transloco-persist-translations
    • @jsverse/transloco-preload-langs
    • @jsverse/transloco-utils
    • @jsverse/transloco-scoped-libs
    • @jsverse/transloco-scoped-validator

    API Changes

    • Transpiler: The transpile method signature has changed to accept an object.
    • setTranslationKey: The lang parameter has been moved into the configuration object.

  12. Migrate from ngx-translate to Transloco

    master

    Use the Transloco migration schematic to automatically convert your project from ngx-translate to @jsverse/transloco. The script recursively iterates over all HTML and TS files to replace pipes, directives, imports, constructor injections, service usages, and module declarations.

    Note: Some manual changes may still be required after the script has finished running.

    ng g @jsverse/transloco:migrate