@gilsdav/ngx-translate-router

中文文档
8.0.0发布于 2025/12/16MITTypeScriptES Module近 30 天下载 2.2万

An implementation of routes localization for Angular.

原始使用文档
文档目录15 节
  1. Installation
  2. Usage
  3. Initialize "module"
  4. Server side
  5. How it works
  6. Pipe
  7. Service
  8. AOT
  9. API
  10. LocalizeRouterModule
  11. LocalizeRouterConfig
  12. LocalizeRouterService
  13. LocalizeParser
  14. License
  15. Thanks

ngx-translate-router (deprecated)

An implementation of routes localization for Angular.

[!CAUTION] It is with a heavy heart that I must announce (despite the fact that you have probably already noticed) that I'm no longer able to maintain this library in my free time due to personal reasons. It is entirely open-source with an MIT license, so I would be happy to see someone else take it over. Thank you to all the users for these fantastic years. Advice for the next person: don't do it alone.

  • ngx-translate-router npm version
  • ngx-translate-router-http-loader npm version
  • ngx-translate-router-scully-plugin npm version (Documentation here)

Fork of localize-router.

Based on and extension of ngx-translate.

Version to choose :

angular versiontranslate-routerhttp-loadertyperemarks
6 - 71.0.21.0.1legacy
71.7.31.1.0legacy
82.2.31.1.0legacy
8 - 123.1.91.1.2legacy
134.0.12.0.0legacy
145.1.12.0.0legacyneed rxjs 7 or higher
156.0.02.0.0legacyminimum angular 15.0.3
15.16.1.02.0.0legacyminimum angular 15.1.0
167.0.02.0.0legacyminimum angular 16
177.1.02.0.0legacyoptional standalone API
187.2.12.0.0legacy
188.0.02.0.0active@ngx-translate/core v17+

Demo project can be found under sub folder src.

This documentation is for version 1.x.x which requires Angular 6+. If you are migrating from the older version follow migration guide to upgrade to latest version.

Table of contents:

Installation

npm install --save @gilsdav/ngx-translate-router

Usage

In order to use @gilsdav/ngx-translate-router you must initialize it with following information:

  • Available languages/locales
  • Prefix for route segment translations
  • Routes to be translated

Initialize "module"

Module mode

import {LocalizeRouterModule} from '@gilsdav/ngx-translate-router'; Module can be initialized either using static file or manually by passing necessary values.

Be careful to import this module after the standard RouterModule and the TranslateModule. This should be done for the main router as well as for lazy loaded ones.

imports: [
  TranslateModule.forRoot(),
  RouterModule.forRoot(routes),
  LocalizeRouterModule.forRoot(routes) // <--
]

Standalone mode

Standalone mode is the new Angular API that allow you to manage your application without ng-modules.

This library provide an additional "RouterConfigurationFeature" called withLocalizeRouter you can provide to provideRouter Angular built-in function. Parameters for this function are exactly the same as for LocalizeRouterModule.forRoot().

Here is an example to configure it within an SSR app:

providers: [
  provideHttpClient(withFetch()),
  importProvidersFrom(TranslateModule.forRoot()),
  provideRouter(
    routes,
    withDisabledInitialNavigation(),
    withLocalizeRouter(routes, { // <--
      parser: {
        provide: LocalizeParser,
        useFactory: (createTranslateRouteLoader),
        deps: [TranslateService, Location, LocalizeRouterSettings]
      },
      initialNavigation: true
    })
  ),
  provideClientHydration()
]

You are also able to import LocalizeRouterPipe into your standalone components.

Http loader

In order to use Http loader for config files, you must include @gilsdav/ngx-translate-router-http-loader package and use its LocalizeRouterHttpLoader.

import {BrowserModule} from "@angular/platform-browser";
import {NgModule} from '@angular/core';
import {Location} from '@angular/common';
import {HttpClientModule, HttpClient} from '@angular/common/http';
import {TranslateModule} from '@ngx-translate/core';
import {LocalizeRouterModule} from '@gilsdav/ngx-translate-router';
import {LocalizeRouterHttpLoader} from '@gilsdav/ngx-translate-router-http-loader';
import {RouterModule} from '@angular/router';

import {routes} from './app.routes';

@NgModule({
  imports: [
    BrowserModule,
    HttpClientModule,
    TranslateModule.forRoot(),
    RouterModule.forRoot(routes),
    LocalizeRouterModule.forRoot(routes, {
      parser: {
        provide: LocalizeParser,
        useFactory: (translate, location, settings, http) =>
            new LocalizeRouterHttpLoader(translate, location, settings, http),
        deps: [TranslateService, Location, LocalizeRouterSettings, HttpClient]
      }
    })
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

More details are available on localize-router-http-loader.

If you are using child modules or routes you need to initialize them with forChild command:

@NgModule({
  imports: [
    TranslateModule,
    RouterModule.forChild(routes),
    LocalizeRouterModule.forChild(routes)
  ],
  declarations: [ChildComponent]
})
export class ChildModule { }

Manual initialization

With manual initialization you need to provide information directly:

LocalizeRouterModule.forRoot(routes, {
    parser: {
        provide: LocalizeParser,
        useFactory: (translate, location, settings) =>
            new ManualParserLoader(translate, location, settings, ['en','de',...], 'YOUR_PREFIX'),
        deps: [TranslateService, Location, LocalizeRouterSettings]
    }
})

Initialization config

Apart from providing routes which are mandatory, and parser loader you can provide additional configuration for more granular setting of @gilsdav/ngx-translate-router. More information at LocalizeRouterConfig.

Server side

In order to use @gilsdav/ngx-translate-router in Angular universal application (SSR) you need to:

  1. Initialize the module

  2. In case you opted for initializing with Http loader, you need to take care of static file location. @gilsdav/ngx-translate-router-http-loader by default will try loading the config file from assets/locales.json. This is a relative path which won't work with SSR. You could use one of the following approaches,

    1. Creating a factory function to override the default location with an absolute URL
      export function localizeLoaderFactory(translate: TranslateService, location: Location, settings: LocalizeRouterSettings, http: HttpClient) {
        return new LocalizeRouterHttpLoader(translate, location, settings, http, 'http://example.com/assets/locales.json');
      }
       
      LocalizeRouterModule.forRoot(routes, {
        parser: {
          provide: LocalizeParser,
          useFactory: localizeLoaderFactory,
          deps: [TranslateService, Location, LocalizeRouterSettings, HttpClient]
        }
      })
      
    2. Using an HTTP interceptor in your server.module to convert relative paths to absolute ons, ex:
      intercept(request: HttpRequest<any>, next: HttpHandler) {
        if (request.url.startsWith('assets') && isPlatformServer(this.platformId)) {
          const req = this.injector.get(REQUEST);
          const url = req.protocol + '://' + req.get('host') + '/' + request.url;
          request = request.clone({
            url: url
          });
        }
        return next.handle(request);
      }
      
      
  3. Let node server knows about the new routes:

    let fs = require('fs');
    let data: any = JSON.parse(fs.readFileSync(`src/assets/locales.json`, 'utf8'));
     
    app.get('/', ngApp);
    data.locales.forEach(route => {
      app.get(`/${route}`, ngApp);
      app.get(`/${route}/*`, ngApp);
    });
    
  4. In case you want to use cacheMechanism = CacheMechanism.Cookie you will need to handle the cookie in your node server. Something like,

    app.use(cookieParser());
    
    app.get('/', (req, res) => {
      const defaultLang = 'de';
      const lang = req.acceptsLanguages('de', 'en');
      const cookieLang = req.cookies.LOCALIZE_DEFAULT_LANGUAGE; // This is the default name of cookie
    
      const definedLang = cookieLang || lang || defaultLang;
    
      res.redirect(301, `/${definedLang}/`);
    });
    

Gotchas

  • In case you are using domino in your project, you will face the following error

    ERROR TypeError: Cannot read property 'indexOf' of undefined
    at TranslateService.getBrowserLang
    

    to overcome this, use the following:

    // language is readonly so normally you can't assign a value to it.
    // The following comments remove the compile time error and the IDE warning
    // @ts-ignore
    // noinspection JSAnnotator
    window.navigator.language = 'en';
    

Deal with initialNavigation

When you add Universal into your app you will have initialNavigation set to "enabled". This is to avoid the flickering of the lazy-load.

Unfortunatly it doesn't help with this library and can cause issues. So you need to set it to "disabled" and add the ngx-translate-router option initialNavigation: true to have this desired behavior.

imports: [
  RouterModule.forRoot(routes, { initialNavigation: 'disabled' }),
  LocalizeRouterModule.forRoot(routes, {
    ...
    initialNavigation: true
  })
]

How it works

@gilsdav/ngx-translate-router intercepts Router initialization and translates each path and redirectTo path of Routes. The translation process is done with ngx-translate. In order to separate router translations from normal application translations we use prefix. Default value for prefix is ROUTES.. Finally, in order to avoid accidentally translating a URL segment that should not be translated, you can optionally use escapePrefix so the prefix gets stripped and the segment doesn't get translated. Default escapePrefix is unset.

'home' -> 'ROUTES.home'

Example to escape the translation of the segment with escapePrefix: '!'

'!segment' -> 'segment'
{ path: '!home/first' ... } -> '/fr/home/premier'

Upon every route change @gilsdav/ngx-translate-router kicks in to check if there was a change to language. Translated routes are prepended with two letter language code:

http://yourpath/home -> http://yourpath/en/home

If no language is provided in the url path, application uses:

  • cached language in LocalStorage/SessionStorage/Cookie (browser only) or
  • current language of the browser (browser only) or
  • first locale in the config

Make sure you therefore place most common language (e.g. 'en') as a first string in the array of locales.

Note that ngx-translate-router does not redirect routes like my/route to translated ones e.g. en/my/route. All routes are prepended by currently selected language so route without language is unknown to Router.

Excluding routes

Sometimes you might have a need to have certain routes excluded from the localization process e.g. login page, registration page etc. This is possible by setting flag skipRouteLocalization on route's data object.

In case you want to redirect to an url when skipRouteLocalization is activated, you can also provide config option localizeRedirectTo to skip route localization but localize redirect to. Otherwise, route and redirectTo will not be translated.

let routes = [
  // this route gets localized
  { path: 'home', component: HomeComponent },
  // this route will not be localized
  { path: 'login', component: LoginComponent, data: { skipRouteLocalization: true } }
    // this route will not be localized, but redirect to will do
  { path: 'logout', redirectTo: 'login', data: { skipRouteLocalization: { localizeRedirectTo: true } } }
];

Note that this flag should only be set on root routes. By excluding root route, all its sub routes are automatically excluded. Setting this flag on sub route has no effect as parent route would already have or have not language prefix.

ngx-translate integration

LocalizeRouter depends on ngx-translate core service and automatically initializes it with selected locales. Following code is run on LocalizeParser init:

this.translate.setFallbackLang(cachedLanguage || languageOfBrowser || firstLanguageFromConfig);
// ...
this.translate.use(languageFromUrl || cachedLanguage || languageOfBrowser || firstLanguageFromConfig);

Both languageOfBrowser and languageFromUrl are cross-checked with locales from config.

Path discrimination

Do you use same path to load multiple lazy-loaded modules and you have wrong component tree ? discriminantPathKey will help ngx-translate-router to generate good component tree.

  {
    path: '',
    loadChildren: () => import('app/home/home.module').then(m => m.HomeModule),
    data: {
        discriminantPathKey: 'HOMEPATH'
    }
  },
  {
    path: '',
    loadChildren: () => import('app/information/information.module').then(m => m.InformationModule),
    data: {
        discriminantPathKey: 'INFOPATH'
    }
  }

WildCard Path

Favored way

The favored way to use WildCard ( '**' path ) is to use the redirectTo. It will let the user to translate the "not found" page message.

{
  path: '404',
  component: NotFoundComponent
},
{
  path: '**',
  redirectTo: '/404'
}
Alternative

If you need to keep the wrong url you will face to a limitation: You can not translate current page. This limitation is because we can not determine the language from a wrong url.

{
  path: '**',
  component: NotFoundComponent
}

Matcher params translation

Configure routes

In case you want to translate some params of matcher, localizeMatcher provides you the way to do it through a function per each param. Make sure that the key is the same as the one used in the navigate path (example: if the function returns "map", it must be contained in the not localized path: [routerLink]="['/matcher', 'aaa', 'map'] | localize") otherwise you will not be able to use routerLinkActiveOptions.

Example:

{
  path: 'matcher',
  children: [
    {
      matcher: detailMatcher,
      loadChildren: () => import('./matcher/matcher-detail/matcher-detail.module').then(mod => mod.MatcherDetailModule)
    },
    {
      matcher: baseMatcher,
      loadChildren: () => import('./matcher/matcher.module').then(mod => mod.MatcherModule),
      data: {
        localizeMatcher: {
          params: {
            mapPage: shouldTranslateMap
          }
        }
      }
    }
  ]
}

...

export function shouldTranslateMap(param: string): string {
  if (isNaN(+param)) {
    return 'map';
  }
  return null;
}

The output of the function should be falsy if the param must not be translated or should return the key (without prefix) you want to use when translating if you want to translate the param.

Notice that any function that you use in localizeMatcher must be exported to be compatible with AOT.

Small changes to your matcher

We work with UrlSegment to split URL into "params" in basic UrlMatchResult but there is not enough information to apply the translations.

You must use the LocalizedMatcherUrlSegment type to more strongly associate a segment with a parameter. It contains only the localizedParamName attribute in addition to basic UrlSegment. Set this attribute before adding the segment into consumed and posParams.

const result: UrlMatchResult = {
  consumed: [],
  posParams: { }
};

...

(segment as LocalizedMatcherUrlSegment).localizedParamName = name;
result.consumed.push(segment);
result.posParams[name] = segment;
Matcher params translated without localizeMatcher issue

If the URL is accidentally translated from a language to another which creates an inconsistent state you have to enable escapePrefix mechanism. (example: escapePrefix: '!')

RedirectTo with function

Starting in Angular 18 introduced redirectTo as a function in addition to a string. If you use this feature, you can use the redirectTo function to translate the path. However, the library translates the entire router at the start of the application statically, which means that the translate function has no yet the navigation context of the user in that moment as it should be evaluated dynamically once the user navigates to such route. If you want to use this feature, you can use the LocalizeRouterService to translate the path injecting the service as in this example.

{
  path: 'conditionalRedirectTo', redirectTo: ({ queryParams }) => {
    const localizeRouterService = inject(LocalizeRouterService);
    if (queryParams['redirect']) {
      return localizeRouterService.translateRoute('/test') as string;
    }
    return localizeRouterService.translateRoute('/home') as string;
  }
}

Pipe

LocalizeRouterPipe is used to translate routerLink directive's content. Pipe can be appended to partial strings in the routerLink's definition or to entire array element:

<a [routerLink]="['user', userId, 'profile'] | localize">{{'USER_PROFILE' | translate}}</a>
<a [routerLink]="['about' | localize]">{{'ABOUT' | translate}}</a>

Root routes work the same way with addition that in case of root links, link is prepended by language. Example for german language and link to 'about':

'/about' | localize -> '/de/über'

Service

Routes can be manually translated using LocalizeRouterService. This is important if you want to use router.navigate for dynamical routes.

class MyComponent {
    constructor(private localize: LocalizeRouterService) { }

    myMethod() {
        let translatedPath: any = this.localize.translateRoute('about/me');
       
        // do something with translated path
        // e.g. this.router.navigate([translatedPath]);
    }
}

AOT

In order to use Ahead-Of-Time compilation any custom loaders must be exported as functions. This is the implementation currently in the solution:

export function localizeLoaderFactory(translate: TranslateService, location: Location, http: Http) {
  return new StaticParserLoader(translate, location, http);
}

API

LocalizeRouterModule

Methods:

  • forRoot(routes: Routes, config: LocalizeRouterConfig = {}): ModuleWithProviders: Main initializer for @gilsdav/ngx-translate-router. Can provide custom configuration for more granular settings.
  • forChild(routes: Routes): ModuleWithProviders: Child module initializer for providing child routes.

LocalizeRouterConfig

Properties

  • parser: Provider for loading of LocalizeParser. Default value is StaticParserLoader.
  • useCachedLang: boolean. Flag whether default language should be cached. Default value is true.
  • alwaysSetPrefix: boolean. Flag whether language should always prefix the url. Default value is true.
    When value is false, prefix will not be used for for default language (this includes the situation when there is only one language).
  • cacheMechanism: CacheMechanism.LocalStorage || CacheMechanism.SessionStorage || CacheMechanism.Cookie. Default value is CacheMechanism.LocalStorage.
  • cacheName: string. Name of cookie/local store. Default value is LOCALIZE_DEFAULT_LANGUAGE.
  • defaultLangFunction: (languages: string[], cachedLang?: string, browserLang?: string) => string. Override method for custom logic for picking default language, when no language is provided via url. Default value is undefined.
  • cookieFormat: string. Format of cookie to store. Default value is '{{value}};{{expires}}'. (Extended format e.g : '{{value}};{{expires}};path=/')
    • {{value}} will be replaced by the value to save (CACHE_NAME=language). Must be present into format.
    • {{expires}} will be replaced by expires=currentDate+30days. Optional if you want session cookie.
      • you can configure the number of expiration days by using this synthax: {{expires:365}}. It will result as expires=currentDate+365days.
    • results to : LOCALIZE_DEFAULT_LANGUAGE=en;expires=Wed, 11 Sep 2019 21:19:23 GMT.

LocalizeRouterService

Properties:

  • routerEvents: An EventEmitter to listen to language change event
localizeService.routerEvents.subscribe((language: string) => {
    // do something with language
});
  • parser: Used instance of LocalizeParser
let selectedLanguage = localizeService.parser.currentLang;

Methods:

  • translateRoute(path: string | any[]): string | any[]: Translates given path. If path starts with backslash then path is prepended with currently set language.
localizeService.translateRoute('/'); // -> e.g. '/en'
localizeService.translateRoute('/about'); // -> '/de/ueber-uns' (e.g. for German language)
localizeService.translateRoute('about'); // -> 'ueber-uns' (e.g. for German language)
  • changeLanguage(lang: string, extras?: NavigationExtras, useNavigateMethod?: boolean): Translates current url to given language and changes the application's language. extras will be passed down to Angular Router navigation methods. userNavigateMethod tells localize-router to use navigate rather than navigateByUrl method.
    For german language and route defined as :lang/users/:user_name/profile
yoursite.com/en/users/John%20Doe/profile -> yoursite.com/de/benutzer/John%20Doe/profil

Hooks:

For now there is only one hook which is only interesting if you are using initialNavigation flag (and more specifically, if you are making an AppInitializer that uses Angular's Router or ngx-translate-router).

  • hooks.initialized: an observable with event sent when initialNavigation is executed.

Usage example:

export const appInitializerFactory = (injector: Injector) => {
  return () => {
    const localize = injector.get(LocalizeRouterService);
    return firstValueFrom(
      localize.hooks.initialized
        .pipe(
          tap(() => {
            const router = injector.get(Router);
            router.events.pipe(
              filter(url => url instanceof NavigationEnd),
              first()
            ).subscribe((route: NavigationEnd) => {
              console.log(router.url, route.url);
              router.navigate(['/fr/accueil']);
            });
          })
        )
      )
  }
};

LocalizeParser

Properties:

  • locales: Array of used language codes
  • currentLang: Currently selected language
  • routes: Active translated routes
  • urlPrefix: Language prefix for current language. Empty string if alwaysSetPrefix=false and currentLang is same as default language.

Methods:

  • translateRoutes(language: string): Observable<any>: Translates all the routes and sets language and current language across the application.
  • translateRoute(path: string): string: Translates single path
  • getLocationLang(url?: string): string: Extracts language from current url if matching defined locales

License

Licensed under MIT

Thanks

Thanks to all our contributors

As well as to all the contributors of the initial project Made with contributors-img.

版本与发布记录

@gilsdav/ngx-translate-router 共发布 48 个版本,首次发布于 2018/07/05;过去 12 个月发布了 1 个版本。

版本发布日期距今
8.0.0latest2025/12/1611 个月前
7.2.12024/06/172 年前
7.2.02024/06/172 年前
7.1.02024/03/292 年前
7.1.0-rc1rc2023/11/292 年前
7.0.02023/11/282 年前

其他发布通道:ng7 → 1.7.3,ng8 → 2.2.3,ng12 → 3.1.9,rc → 7.1.0-rc1。

关于 @gilsdav/ngx-translate-router 的常见问题

@gilsdav/ngx-translate-router 是什么?

An implementation of routes localization for Angular.

如何安装 @gilsdav/ngx-translate-router?

在项目目录运行 npm install @gilsdav/ngx-translate-router,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@angular/common(>=16.2.12)、@angular/core(>=16.2.12)、@angular/router(>=16.2.12)、@ngx-translate/core(>=17.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gilsdav/ngx-translate-router 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gilsdav/ngx-translate-router 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gilsdav/ngx-translate-router 可以商用吗?

@gilsdav/ngx-translate-router 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gilsdav/ngx-translate-router 的下载量有多少?

根据 npm 官方下载统计,@gilsdav/ngx-translate-router 在 2026/10/17 – 2026/11/15 这 30 天内被下载 21,845 次,日均约 728 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gilsdav/ngx-translate-router 还在维护吗?

最新版本 8.0.0 发布于 2025/12/16(11 个月前);至今共发布 48 个版本,其中过去 12 个月发布了 1 个;首次发布于 2018/07/05。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。