{"id":21514180,"url":"https://github.com/greentube/localize-router","last_synced_at":"2025-04-05T17:03:57.240Z","repository":{"id":12315598,"uuid":"71144359","full_name":"Greentube/localize-router","owner":"Greentube","description":"An implementation of routes localisation for Angular","archived":false,"fork":false,"pushed_at":"2023-01-04T16:55:52.000Z","size":2277,"stargazers_count":193,"open_issues_count":70,"forks_count":93,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-29T16:03:33.898Z","etag":null,"topics":["angular","aot","aot-compatible","i18n","localization","localized-router","ng2-translate","router","typescript","universal"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Greentube.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-17T13:59:27.000Z","updated_at":"2024-09-10T23:01:17.000Z","dependencies_parsed_at":"2023-01-13T18:15:21.129Z","dependency_job_id":null,"html_url":"https://github.com/Greentube/localize-router","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Greentube%2Flocalize-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Greentube%2Flocalize-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Greentube%2Flocalize-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Greentube%2Flocalize-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Greentube","download_url":"https://codeload.github.com/Greentube/localize-router/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369953,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","aot","aot-compatible","i18n","localization","localized-router","ng2-translate","router","typescript","universal"],"created_at":"2024-11-23T23:43:12.543Z","updated_at":"2025-04-05T17:03:57.223Z","avatar_url":"https://github.com/Greentube.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# localize-router\n[![Build Status](https://travis-ci.org/Greentube/localize-router.svg?branch=master)](https://travis-ci.org/Greentube/localize-router)\n[![Build Status](https://circleci.com/gh/Greentube/localize-router.svg?style=shield)](https://circleci.com/gh/Greentube/localize-router)\n[![npm version](https://img.shields.io/npm/v/localize-router.svg)](https://www.npmjs.com/package/localize-router)\n\u003e An implementation of routes localization for Angular.\n\nBased on and extension of [ngx-translate](https://github.com/ngx-translate/core).\nDemo project can be found [here](https://github.com/meeroslav/localize-router-example) or under sub folder `demo/cli`.\n\n\u003e This documentation is for version 2.x.x which requires Angular 6+. If you are using the Angular 5 please refer to version 1.x.x. If you are migrating from the older version follow [migration guide](https://github.com/Greentube/localize-router/blob/master/MIGRATION_GUIDE.md) to upgrade to latest version.\n\n# Table of contents:\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Initialize module](#initialize-module)\n        - [Http loader](#http-loader)\n        - [Initialization config](#initialization-config)\n        - [Manual initialization](#manual-initialization)\n        - [Server side initialization](#server-side-initialization)\n    - [How it works](#how-it-works)\n        - [excluding-routes](#excluding-routes)\n        - [ngx-translate integration](#ngx-translate-integration)\n    - [Pipe](#pipe)\n    - [Service](#service)\n    - [AOT](#aot)\n- [API](#api)\n    - [LocalizeRouterModule](#localizeroutermodule)\n    - [LocalizeRouterConfig](#localizerouterconfig)\n    - [LocalizeRouterService](#localizerouterservice)\n    - [LocalizeParser](#localizeparser)\n- [License](#license)\n\n## Installation\n\n```\nnpm install --save localize-router\n```\n\n## Usage\n\nIn order to use `localize-router` you must initialize it with following information:\n* Available languages/locales\n* Prefix for route segment translations\n* Routes to be translated\n\n### Initialize module\nModule can be initialized either using static file or manually by passing necessary values.\n\n#### Http loader\n\nIn order to use Http loader for config files, you must include `localize-router-http-loader` package and use its `LocalizeRouterHttpLoader`. \n\n```ts\nimport {BrowserModule} from \"@angular/platform-browser\";\nimport {NgModule} from '@angular/core';\nimport {Location} from '@angular/common';\nimport {HttpClientModule, HttpClient} from '@angular/common/http';\nimport {TranslateModule} from '@ngx-translate/core';\nimport {LocalizeRouterModule} from 'localize-router';\nimport {LocalizeRouterHttpLoader} from 'localize-router-http-loader';\nimport {RouterModule} from '@angular/router';\n\nimport {routes} from './app.routes';\n\n@NgModule({\n  imports: [\n    BrowserModule,\n    HttpClientModule,\n    TranslateModule.forRoot(),\n    LocalizeRouterModule.forRoot(routes, {\n      parser: {\n        provide: LocalizeParser,\n        useFactory: (translate, location, settings, http) =\u003e\n            new LocalizeRouterHttpLoader(translate, location, settings, http),\n        deps: [TranslateService, Location, LocalizeRouterSettings, HttpClient]\n      }\n    }),\n    RouterModule.forRoot(routes)\n  ],\n  bootstrap: [AppComponent]\n})\nexport class AppModule { }\n```\n\nMore details are available on [localize-router-http-loader](https://github.com/Greentube/localize-router-http-loader).\n\nIf you are using child modules or routes you need to initialize them with `forChild` command:\n```ts\n@NgModule({\n  imports: [\n    TranslateModule,\n    LocalizeRouterModule.forChild(routes),\n    RouterModule.forChild(routes)\n  ],\n  declarations: [ChildComponent]\n})\nexport class ChildModule { }\n```\n\n#### Initialization config\nApart from providing routes which are mandatory, and parser loader you can provide additional configuration for more granular setting of `localize router`. More information at [LocalizeRouterConfig](#localizerouterconfig). \n\n\n#### Manual initialization\n   With manual initialization you need to provide information directly:\n   ```ts\n   LocalizeRouterModule.forRoot(routes, {\n       parser: {\n           provide: LocalizeParser,\n           useFactory: (translate, location, settings) =\u003e\n               new ManualParserLoader(translate, location, settings, ['en','de',...], 'YOUR_PREFIX'),\n           deps: [TranslateService, Location, LocalizeRouterSettings]\n       }\n   })\n   ```\n\n#### Server side initialization\nIn order to use server side initialization in isomorphic/universal projects you need to create loader similar to this:\n```ts\nexport class LocalizeUniversalLoader extends LocalizeParser {\n  /**\n   * Gets config from the server\n   * @param routes\n   */\n  public load(routes: Routes): Promise\u003cany\u003e {\n    return new Promise((resolve: any) =\u003e {\n      let data: any = JSON.parse(fs.readFileSync(`assets/locales.json`, 'utf8'));\n      this.locales = data.locales;\n      this.prefix = data.prefix;\n      this.init(routes).then(resolve);\n    });\n  }\n}\n\nexport function localizeLoaderFactory(translate: TranslateService, location: Location, settings: LocalizeRouterSettings) {\n  return new LocalizeUniversalLoader(translate, location, settings);\n}\n```\n\nDon't forget to create similar loader for `ngx-translate` as well:\n```ts\nexport class TranslateUniversalLoader implements TranslateLoader {\n  /**\n   * Gets the translations from the server\n   * @param lang\n   * @returns {any}\n   */\n  public getTranslation(lang: string): Observable\u003cany\u003e {\n    return Observable.create(observer =\u003e {\n      observer.next(JSON.parse(fs.readFileSync(`src/assets/locales/${lang}.json`, 'utf8')));\n      observer.complete();\n    });\n  }\n}\nexport function translateLoaderFactory() {\n  return new TranslateUniversalLoader();\n}\n```\n\nSince node server expects to know which routes are allowed you can feed it like this:\n```ts\nlet fs = require('fs');\nlet data: any = JSON.parse(fs.readFileSync(`src/assets/locales.json`, 'utf8'));\n\napp.get('/', ngApp);\ndata.locales.forEach(route =\u003e {\n  app.get(`/${route}`, ngApp);\n  app.get(`/${route}/*`, ngApp);\n});\n```\n\nWorking example can be found [here](https://github.com/meeroslav/universal-localize-example).\n\n### How it works\n\n`Localize router` intercepts Router initialization and translates each `path` and `redirectTo` path of Routes.\nThe translation process is done with [ngx-translate](https://github.com/ngx-translate/core). In order to separate \nrouter translations from normal application translations we use `prefix`. Default value for prefix is `ROUTES.`.\n```\n'home' -\u003e 'ROUTES.home'\n```\n\nUpon every route change `Localize router` kicks in to check if there was a change to language. Translated routes are prepended with two letter language code:\n```\nhttp://yourpath/home -\u003e http://yourpath/en/home\n```\n\nIf no language is provided in the url path, application uses: \n* cached language in LocalStorage (browser only) or\n* current language of the browser (browser only) or \n* first locale in the config\n\nMake sure you therefore place most common language (e.g. 'en') as a first string in the array of locales.\n\n\u003e Note that `localize-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.\n\n#### Excluding routes\n\nSometimes 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.\n\n```ts\nlet routes = [\n  // this route gets localized\n  { path: 'home', component: HomeComponent },\n  // this route will not be localized\n  { path: 'login', component: LoginComponent, data: { skipRouteLocalization: true } }\n];\n```\n\nNote that this flag should only be set on root routes. By excluding root route, all its sub routes are automatically excluded.\nSetting this flag on sub route has no effect as parent route would already have or have not language prefix.\n\n#### ngx-translate integration\n\n`LocalizeRouter` depends on `ngx-translate` core service and automatically initializes it with selected locales.\nFollowing code is run on `LocalizeParser` init:\n```ts\nthis.translate.setDefaultLang(cachedLanguage || languageOfBrowser || firstLanguageFromConfig);\n// ...\nthis.translate.use(languageFromUrl || cachedLanguage || languageOfBrowser || firstLanguageFromConfig);\n```\n\nBoth `languageOfBrowser` and `languageFromUrl` are cross-checked with locales from config.\n\n### Pipe\n\n`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:\n```html\n\u003ca [routerLink]=\"['user', userId, 'profile'] | localize\"\u003e{{'USER_PROFILE' | translate}}\u003c/a\u003e\n\u003ca [routerLink]=\"['about' | localize]\"\u003e{{'ABOUT' | translate}}\u003c/a\u003e\n```\n\nRoot routes work the same way with addition that in case of root links, link is prepended by language.\nExample for german language and link to 'about':\n```\n'/about' | localize -\u003e '/de/über'\n```\n\n### Service\n\nRoutes can be manually translated using `LocalizeRouterService`. This is important if you want to use `router.navigate` for dynamical routes.\n\n```ts\nclass MyComponent {\n    constructor(private localize: LocalizeRouterService) { }\n\n    myMethod() {\n        let translatedPath: any = this.localize.translateRoute('about/me');\n       \n        // do something with translated path\n        // e.g. this.router.navigate([translatedPath]);\n    }\n}\n```\n\n### AOT\n\nIn order to use Ahead-Of-Time compilation any custom loaders must be exported as functions.\nThis is the implementation currently in the solution:\n\n```ts\nexport function localizeLoaderFactory(translate: TranslateService, location: Location, http: Http) {\n  return new StaticParserLoader(translate, location, http);\n}\n```\n\n## API\n### LocalizeRouterModule\n#### Methods:\n- `forRoot(routes: Routes, config: LocalizeRouterConfig = {}): ModuleWithProviders`: Main initializer for localize router. Can provide custom configuration for more granular settings.\n- `forChild(routes: Routes): ModuleWithProviders`: Child module initializer for providing child routes.\n### LocalizeRouterConfig\n#### Properties\n- `parser`: Provider for loading of LocalizeParser. Default value is `StaticParserLoader`.\n- `useCachedLang`: boolean. Flag whether default language should be cached. Default value is `true`.\n- `alwaysSetPrefix`: boolean. Flag whether language should always prefix the url. Default value is `true`.  \n  When value is `false`, prefix will not be used for for default language (this includes the situation when there is only one language).\n- `cacheMechanism`: CacheMechanism.LocalStorage || CacheMechanism.Cookie. Default value is `CacheMechanism.LocalStorage`.\n- `cacheName`: string. Name of cookie/local store. Default value is `LOCALIZE_DEFAULT_LANGUAGE`.\n- `defaultLangFunction`: (languages: string[], cachedLang?: string, browserLang?: string) =\u003e string. Override method for custom logic for picking default language, when no language is provided via url. Default value is `undefined`.\n### LocalizeRouterService\n#### Properties:\n- `routerEvents`: An EventEmitter to listen to language change event\n```ts\nlocalizeService.routerEvents.subscribe((language: string) =\u003e {\n    // do something with language\n});\n```\n- `parser`: Used instance of LocalizeParser\n```ts\nlet selectedLanguage = localizeService.parser.currentLang;\n```\n#### Methods:\n- `translateRoute(path: string | any[]): string | any[]`: Translates given path. If `path` starts with backslash then path is prepended with currently set language.\n```ts\nlocalizeService.translateRoute('/'); // -\u003e e.g. '/en'\nlocalizeService.translateRoute('/about'); // -\u003e '/de/ueber-uns' (e.g. for German language)\nlocalizeService.translateRoute('about'); // -\u003e 'ueber-uns' (e.g. for German language)\n```\n- `changeLanguage(lang: string)`: Translates current url to given language and changes the application's language.  \nFor german language and route defined as `:lang/users/:user_name/profile`\n```\nyoursite.com/en/users/John%20Doe/profile -\u003e yoursite.com/de/benutzer/John%20Doe/profil\n```\n### LocalizeParser\n#### Properties:\n- `locales`: Array of used language codes\n- `currentLang`: Currently selected language\n- `routes`: Active translated routes\n- `urlPrefix`: Language prefix for current language. Empty string if `alwaysSetPrefix=false` and `currentLang` is same as default language.\n\n#### Methods:\n- `translateRoutes(language: string): Observable\u003cany\u003e`: Translates all the routes and sets language and current \nlanguage across the application.\n- `translateRoute(path: string): string`: Translates single path\n- `getLocationLang(url?: string): string`: Extracts language from current url if matching defined locales\n\n## License\nLicensed under MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreentube%2Flocalize-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreentube%2Flocalize-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreentube%2Flocalize-router/lists"}