{"id":13807531,"url":"https://github.com/larscom/ngx-translate-module-loader","last_synced_at":"2025-04-06T08:15:34.633Z","repository":{"id":34304514,"uuid":"176234127","full_name":"larscom/ngx-translate-module-loader","owner":"larscom","description":"Highly configurable and flexible translations loader for @ngx-translate/core","archived":false,"fork":false,"pushed_at":"2025-03-27T12:50:03.000Z","size":3752,"stargazers_count":34,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T07:11:15.129Z","etag":null,"topics":["angular","http","i18n","internationalization","l10n","loader","localization","ngx-translate","rxjs","translation"],"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/larscom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-18T08:12:15.000Z","updated_at":"2025-03-27T12:50:06.000Z","dependencies_parsed_at":"2024-01-16T00:58:04.893Z","dependency_job_id":"25e9d577-063c-44d1-9228-05f04bba179b","html_url":"https://github.com/larscom/ngx-translate-module-loader","commit_stats":{"total_commits":156,"total_committers":5,"mean_commits":31.2,"dds":"0.15384615384615385","last_synced_commit":"d3a4ece242f76d73159f8f86d023b8cad13d3ac3"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larscom%2Fngx-translate-module-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larscom%2Fngx-translate-module-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larscom%2Fngx-translate-module-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larscom%2Fngx-translate-module-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/larscom","download_url":"https://codeload.github.com/larscom/ngx-translate-module-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247451667,"owners_count":20940944,"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","http","i18n","internationalization","l10n","loader","localization","ngx-translate","rxjs","translation"],"created_at":"2024-08-04T01:01:26.468Z","updated_at":"2025-04-06T08:15:34.605Z","avatar_url":"https://github.com/larscom.png","language":"TypeScript","readme":"# @larscom/ngx-translate-module-loader\n\n[![npm-version](https://img.shields.io/npm/v/@larscom/ngx-translate-module-loader.svg?label=npm)](https://www.npmjs.com/package/@larscom/ngx-translate-module-loader)\n![npm](https://img.shields.io/npm/dw/@larscom/ngx-translate-module-loader)\n[![license](https://img.shields.io/npm/l/@larscom/ngx-translate-module-loader.svg)](https://github.com/larscom/ngx-translate-module-loader/blob/main/LICENSE)\n\n\n\u003e Highly configurable and flexible translations loader for [@ngx-translate/core](https://github.com/ngx-translate/core). Fetch multiple translations (http only) and configure them to your needs. Each translation file has it's own **namespace** out of the box so the key/value pairs do not conflict with each other.\n\n### ✨ [View on StackBlitz](https://stackblitz.com/edit/ngx-translate-module-loader)\n\n## Dependencies\n\n`@larscom/ngx-translate-module-loader` depends on [@ngx-translate/core](https://github.com/ngx-translate/core) and [Angular](https://github.com/angular/angular).\n\n## Installation\n\n```bash\nnpm i @larscom/ngx-translate-module-loader\n```\n\n## Usage\n\nCreate an exported `moduleHttpLoaderFactory` function\n\n```ts\nimport { NgModule } from '@angular/core'\nimport { BrowserModule } from '@angular/platform-browser'\nimport { HttpClientModule, HttpClient } from '@angular/common/http'\nimport { TranslateModule, TranslateLoader } from '@ngx-translate/core'\nimport { ModuleTranslateLoader, IModuleTranslationOptions } from '@larscom/ngx-translate-module-loader'\nimport { AppComponent } from './app'\n\nexport function moduleHttpLoaderFactory(http: HttpClient) {\n  const baseTranslateUrl = './assets/i18n'\n\n  const options: IModuleTranslationOptions = {\n    modules: [\n      // final url: ./assets/i18n/en.json\n      { baseTranslateUrl },\n      // final url: ./assets/i18n/feature1/en.json\n      { baseTranslateUrl, moduleName: 'feature1' },\n      // final url: ./assets/i18n/feature2/en.json\n      { baseTranslateUrl, moduleName: 'feature2' }\n    ]\n  }\n\n  return new ModuleTranslateLoader(http, options)\n}\n\n@NgModule({\n  imports: [\n    BrowserModule,\n    HttpClientModule,\n    TranslateModule.forRoot({\n      loader: {\n        provide: TranslateLoader,\n        useFactory: moduleHttpLoaderFactory,\n        deps: [HttpClient]\n      }\n    })\n  ],\n  bootstrap: [AppComponent]\n})\nexport class AppModule {\n  constructor(readonly translate: TranslateService) {\n    translate.setDefaultLang('en')\n  }\n}\n```\n\n## Namespacing\n\nBy default, each translation file gets it's own namespace based on the `moduleName`, what does it mean?\n\nFor example with these options:\n\n```ts\nexport function moduleHttpLoaderFactory(http: HttpClient) {\n  const baseTranslateUrl = './assets/i18n'\n\n  const options: IModuleTranslationOptions = {\n    modules: [\n      // no moduleName/namespace\n      { baseTranslateUrl },\n      // namespace: FEATURE1\n      { baseTranslateUrl, moduleName: 'feature1' },\n      // namespace: FEATURE2\n      { baseTranslateUrl, moduleName: 'feature2' }\n    ]\n  }\n  return new ModuleTranslateLoader(http, options)\n}\n```\n\nLets say each module in the **above** example resolves to the following **JSON**:\n\n```json\n{\n  \"KEY\": \"VALUE\"\n}\n```\n\nThe final translation you are working with would be:\n\n```json\n{\n  \"KEY\": \"VALUE\",\n  \"FEATURE1\": {\n    \"KEY\": \"VALUE\"\n  },\n  \"FEATURE2\": {\n    \"KEY\": \"VALUE\"\n  }\n}\n```\n\nEven though all JSON files from those modules are the same, they don't conflict because they are not on the same level after they get merged.\n\n## Configuration\n\nThe configuration is very flexible, you can even define custom templates for fetching translations.\n\n```ts\ninterface IModuleTranslationOptions {\n  /**\n   * The translation module configurations\n   */\n  modules: IModuleTranslation[]\n  /**\n   * By default, each module gets its own namespace so it doesn't conflict with other modules\n   */\n  disableNamespace?: boolean\n  /**\n   * By default, namespaces are uppercase\n   */\n  lowercaseNamespace?: boolean\n  /**\n   * By default, it'll perform a deepmerge when merging translation files\n   */\n  deepMerge?: boolean\n  /**\n   * Set a version to prevent the browser from caching the translation files.\n   * Each translation will get a query parameter with the version number\n   * @example 'en.json?v=123'\n   */\n  version?: string | number\n  /**\n   * Function that gets executed if an error occurred while retrieving a translation file\n   * @param error the error that occurred\n   * @param path the path to the location file\n   */\n  translateError?: (error: any, path: string) =\u003e void\n  /**\n   * Custom translate merge function after retrieving all translation files\n   * @param translations the resolved translation files\n   */\n  translateMerger?: (translations: Translation[]) =\u003e Translation\n  /**\n   * Provide custom headers at 'root' level, which means this headers gets added to every request\n   * unless you specify headers at 'module' level.\n   * @see modules\n   */\n  headers?: HttpHeaders\n}\n```\n\n```ts\ninterface IModuleTranslation {\n  /**\n   * The module name\n   *\n   * For example: shared\n   * @description omit moduleName if you have a translate file at baseTranslateUrl level\n   * @see baseTranslateUrl\n   */\n  moduleName?: string\n  /**\n   * The base translate URL\n   *\n   * For example: ./assets/i18n\n   * @description the final url will then be: ./assets/i18n/shared if the moduleName is shared\n   * @see moduleName\n   */\n  baseTranslateUrl: string\n  /**\n   * By default, it uses the moduleName as namespace\n   * @see moduleName\n   *\n   * Use this property if you want to override the default namespace\n   */\n  namespace?: string\n  /**\n   * Custom translation map function after retrieving a translation file\n   * @param translation the resolved translation file\n   */\n  translateMap?: (translation: Translation) =\u003e Translation\n  /**\n   * Custom path template for fetching translations\n   * @example\n   * '{baseTranslateUrl}/{moduleName}/{language}'\n   * or\n   * @example\n   * '{baseTranslateUrl}/{language}'\n   *\n   * It depends whether you have a moduleName defined\n   * @see moduleName\n   */\n  pathTemplate?: string\n  /**\n   * Provide custom headers at 'module' level. These headers only apply to this module.\n   */\n  headers?: HttpHeaders\n}\n```\n\n## Custom templates for fetching translations\n\nBy default, translations gets fetched by using the following template:\n\n`'{baseTranslateUrl}/{moduleName}/{language}'` e.g. **./assets/feature1/en.json**\n\nYou can override this option if you wish to do so:\n\n```ts\nconst options: IModuleTranslationOptions = {\n  modules: [\n    // resolves to: ./assets/my-path/en.json\n    { baseTranslateUrl, pathTemplate: '{baseTranslateUrl}/my-path/{language}' },\n    // resolves to: ./assets/my-path/en/feature1.json\n    { baseTranslateUrl, moduleName: 'feature1', pathTemplate: '{baseTranslateUrl}/my-path/{language}/{moduleName}' },\n    // resolves to: ./assets/my-path/en/feature2.json\n    { baseTranslateUrl, moduleName: 'feature2', pathTemplate: '{baseTranslateUrl}/my-path/{language}/{moduleName}' }\n  ]\n}\n```\n\n## Custom headers\n\n```ts\n  const options: IModuleTranslationOptions = {\n  // global headers, applied to every request, unless you specify headers at 'module' level\n  headers: new HttpHeaders().set('Header-Name', 'Header value')\n  modules: [\n    { baseTranslateUrl },\n    // headers only applied to this module\n    { baseTranslateUrl, moduleName: 'feature1', headers: new HttpHeaders().set('Header-Name', 'Header value') },\n    { baseTranslateUrl, moduleName: 'feature2' }\n  ]\n};\n```\n","funding_links":[],"categories":["Development Utilities"],"sub_categories":["Internationalization"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarscom%2Fngx-translate-module-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flarscom%2Fngx-translate-module-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarscom%2Fngx-translate-module-loader/lists"}