{"id":19058792,"url":"https://github.com/ngstack/translate","last_synced_at":"2025-04-25T12:31:12.292Z","repository":{"id":34942906,"uuid":"144061187","full_name":"ngstack/translate","owner":"ngstack","description":"Translation library for Angular and Ionic applications.","archived":false,"fork":false,"pushed_at":"2024-10-21T04:37:19.000Z","size":4048,"stargazers_count":23,"open_issues_count":18,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-24T16:19:38.203Z","etag":null,"topics":["angular","angular-component","i18n","internationalization","translation","translation-library","typescript"],"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/ngstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"DenysVuika"}},"created_at":"2018-08-08T19:54:25.000Z","updated_at":"2024-11-07T02:52:09.000Z","dependencies_parsed_at":"2024-07-22T21:07:51.133Z","dependency_job_id":null,"html_url":"https://github.com/ngstack/translate","commit_stats":{"total_commits":730,"total_committers":5,"mean_commits":146.0,"dds":0.5273972602739726,"last_synced_commit":"69308813601cad62e751bb0cae171da9608a3dc2"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngstack%2Ftranslate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngstack%2Ftranslate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngstack%2Ftranslate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngstack%2Ftranslate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngstack","download_url":"https://codeload.github.com/ngstack/translate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250817575,"owners_count":21492176,"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","angular-component","i18n","internationalization","translation","translation-library","typescript"],"created_at":"2024-11-09T00:01:24.199Z","updated_at":"2025-04-25T12:31:11.591Z","avatar_url":"https://github.com/ngstack.png","language":"TypeScript","readme":"# translate\n\nLightweight (±3KB) translation library for Angular applications.\n\n[Live Demo](https://stackblitz.com/edit/ngstack-translate)\n\n\u003ca href=\"https://www.buymeacoffee.com/denys\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"51\" width=\"217\"\u003e\n\u003c/a\u003e\n\n# Table of Contents\n\n\u003c!-- TOC depthfrom:2 --\u003e\n\n- [Installing](#installing)\n- [Using with the application](#using-with-the-application)\n- [Features](#features)\n  - [Translate Pipe](#translate-pipe)\n  - [Title Service](#title-service)\n    - [Translating application title](#translating-application-title)\n  - [Translate Service](#translate-service)\n    - [Using from code](#using-from-code)\n    - [Custom language without external files](#custom-language-without-external-files)\n  - [Formatted translations](#formatted-translations)\n- [Advanced topics](#advanced-topics)\n  - [Testing components](#testing-components)\n  - [Watching for language change](#watching-for-language-change)\n  - [Custom translation path](#custom-translation-path)\n  - [Loading from multiple locations](#loading-from-multiple-locations)\n  - [Cache busting](#cache-busting)\n  - [Define active language](#define-active-language)\n  - [Restricting supported languages](#restricting-supported-languages)\n  - [Using with your own pipes](#using-with-your-own-pipes)\n  - [Lazy Loading](#lazy-loading)\n- [See also](#see-also)\n\n\u003c!-- /TOC --\u003e\n\n## Installing\n\n```sh\nnpm install @ngstack/translate\n```\n\n### Compatibility with Angular\n\n| @ngstack/translate | Angular |\n|--------------------|---------|\n| 8.0.0              | 15      |\n| 9.0.0              | 16      |\n| 10.0.0             | 17      |\n\n## Using with the application\n\nCreate `en.json` file in the `src/app/assets/i18n` folder of your application.\n\n```json\n{\n  \"TITLE\": \"Hello from NgStack/translate!\"\n}\n```\n\nImport `TranslateModule` into you main application module,\nconfigure `TranslateService` to load during application startup.\n\nYou will also need `HttpClientModule` module dependency.\n\n```ts\nimport { NgModule, APP_INITIALIZER } from '@angular/core';\nimport { HttpClientModule } from '@angular/common/http';\nimport { TranslateModule } from '@ngstack/translate';\n\n// needed to load translation before application starts\nexport function setupTranslateService(service: TranslateService) {\n  return () =\u003e service.load();\n}\n\n@NgModule({\n  imports: [\n    BrowserModule,\n    HttpClientModule,\n    TranslateModule.forRoot({\n      // options\n    })\n  ],\n  providers: [\n    // needed to load translation before application starts\n    {\n      provide: APP_INITIALIZER,\n      useFactory: setupTranslateService,\n      deps: [TranslateService],\n      multi: true\n    }\n  ],\n  declarations: [AppComponent],\n  bootstrap: [AppComponent]\n})\nexport class AppModule {}\n```\n\nIn the main application template, use the following snippet:\n\n```html\n\u003ch2\u003e\n  {{ 'TITLE' | translate }}\n\u003c/h2\u003e\n```\n\n## Features\n\n### Translate Pipe\n\n- `\u003celement\u003e{{ 'KEY' | translate }}\u003c/element\u003e`\n- `\u003celement [attribute]=\"property | translate\"\u003e\u003c/element\u003e`\n- `\u003celement attribute=\"{{ property | translate }}\"\u003e\u003c/element\u003e`\n- `\u003celement [innerHTML]=\"'KEY' | translate\"\u003e\u003c/element\u003e`\n- `\u003celement\u003e{{ 'PROPERTY.PATH' | translate }}\u003c/element\u003e`\n- `\u003celement\u003e{{ 'FORMAT' | translate:params }}\u003c/element\u003e`\n- (2.3.0) `\u003celement [translate]=\"'KEY'\"\u003e\u003c/element\u003e`\n- (2.3.0) `\u003celement [translate]=\"'FORMAT'\" [translateParams]=\"{ msg: hello }\"\u003e\u003c/element\u003e`\n- (2.3.0) `\u003celement translate=\"KEY\"\u003e\u003c/element\u003e`\n\n### Title Service\n\n- Sets page title value with automatic translation\n- Watches for language changes and updates the title accordingly\n\n#### Translating application title\n\nUpdate the localization files for your application and add `APP.TITLE` resource key:\n\n```json\n{\n  \"APP\": {\n    \"TITLE\": \"My Application\"\n  }\n}\n```\n\nUpdate the title from the code, the main application component is a perfect place for that:\n\n```ts\nimport { TitleService } from '@ngstack/translate';\n\n@Component({...})\nexport class AppComponent implements OnInit {\n  constructor(private titleService: TitleService) {}\n\n  ngOnInit() {\n    this.titleService.setTitle('APP.TITLE');\n  }\n}\n```\n\nNow every time the language is changed, the page title is going to get changed automatically.\n\n### Translate Service\n\n- Load translations on language change\n- Translation from code\n- Defining translation data from code\n- Merging multiple translations\n- Loading translations from multiple locations\n- Automatic fallback for missing translations\n- Defining supported languages\n- Configurable cache busting\n- Lazy loading support\n- Visual debugging mode to simplify development and testing\n\n#### Using from code\n\nYou can import and use translate service in the code:\n\n```ts\n@Component({...})\nexport class MyComponent {\n\n  text: string;\n\n  constructor(translate: TranslateService) {\n\n    this.text = translate.get('SOME.PROPERTY.PATH');\n\n  }\n\n}\n```\n\n#### Custom language without external files\n\nAn example for providing translation data from within the application,\nwithout loading external files.\n\n```ts\n@NgModule({...})\nexport class AppModule {\n  constructor(translate: TranslateService) {\n    translate.use('en', {\n      'TITLE': 'Hello from @ngstack/translate!'\n    });\n  }\n}\n```\n\n### Formatted translations\n\nYou can use runtime string substitution when translating text\n\n```json\n{\n  \"FORMATTED\": {\n    \"HELLO_MESSAGE\": \"Hello, {username}!\"\n  }\n}\n```\n\nThen in the HTML:\n\n```html\n\u003cdiv\u003e{{ 'FORMATTED.HELLO_MESSAGE' | translate:{ 'username': 'world' } }}\u003c/div\u003e\n```\n\nOr in the Code:\n\n```ts\n@Component({...})\nexport class MyComponent {\n\n  text: string;\n\n  constructor(translate: TranslateService) {\n\n    this.text = translate.get(\n      'FORMATTED.HELLO_MESSAGE',\n      { username: 'world' }\n    );\n\n  }\n\n}\n```\n\nShould produce the following result at runtime:\n\n```text\nHello, world!\n```\n\nYou can use multiple values in the format string.\nNote, however, that TranslateService checks only the top-level properties of the parameter object.\n\n## Advanced topics\n\nYou can provide custom parameters for the `forRoot` method of the `TranslateModule`\n\n```ts\ninterface TranslateSettings {\n  debugMode?: boolean;\n  disableCache?: boolean;\n  supportedLangs?: string[];\n  translationRoot?: string;\n  translatePaths?: string[];\n  activeLang?: string;\n}\n```\n\nFor example:\n\n```ts\nTranslateModule.forRoot({\n  debugMode: true,\n  activeLang: 'fr'\n});\n```\n\n### Testing components\n\nWhen testing localisation with a single translation file it is sometimes hard to tell\nif a component text switches to a different language.\nYou can simplify testing of the end-applications and components by enabling the debug mode.\n\nWhile in the debug mode, the service automatically prepends active language id to very translated result.\nThat allows to verify that your components support i18n correctly and do not contain hard-coded text.\n\n```ts\nTranslateModule.forRoot({\n  debugMode: true\n});\n```\n\nNow, if using `en` as the active language, all strings should start with the `[en]` prefix.\n\n### Watching for language change\n\nYou can watch for language change event utilising the `activeLangChanged` event:\n\n```ts\n@Component({...})\nexport class MyComponent {\n\n  constructor(translate: TranslateService) {\n\n    translate.activeLangChanged.subscribe(\n      (event: { previousValue: string; currentValue: string }) =\u003e {\n        console.log(event.previousValue);\n        console.log(event.currentValue);\n      }\n    );\n\n  }\n}\n```\n\n### Custom translation path\n\nBy default TranslateService loads files stored at `assets/i18n` folder.\nYou can change the `TranslateService.translationRoot` property to point to a custom location if needed.\n\n```ts\nTranslateModule.forRoot({\n  translationRoot: '/some/path'\n});\n```\n\n### Loading from multiple locations\n\nTo provide multiple locations use the `TranslateService.translatePaths` collection property.\n\n```ts\nTranslateModule.forRoot({\n  translatePaths: ['assets/lib1/i18n', 'assets/lib2/i18n']\n});\n```\n\nThe files are getting fetched and merged in the order of declarations,\nand applied on the top of the default data loaded from `TranslateService.translationRoot` path.\n\n### Cache busting\n\nYou can disable browser caching and force application always load translation files by using `TranslateService.disableCache` property.\n\n```ts\nTranslateModule.forRoot({\n  disableCache: true\n});\n```\n\n### Define active language\n\nThe service takes browser language as an active language at startup.\nYou can use `activeLang` property to define a custom value and override browser settings.\n\n```ts\nTranslateModule.forRoot({\n  activeLang: 'fr'\n});\n```\n\n### Restricting supported languages\n\nIt is possible to restrict supported languages to a certain set of values.\nYou can avoid unnecessary HTTP calls by providing `TranslateService.supportedLangs` values.\n\n```ts\nTranslateModule.forRoot({\n  supportedLangs: ['fr', 'de']\n});\n```\n\nThe service will try to load resource files only for given set of languages,\nand will use fallback language for all unspecified values.\n\nBy default this property is empty and service will probe all language files.\nThe service always takes into account the Active and Fallback languages, even if you do not specify them in the list.\n\n### Using with your own pipes\n\nIt is possible to use `TranslateService` with your own implementations.\n\nYou can see the basic pipe implementation below:\n\n```ts\nimport { Pipe, PipeTransform } from '@angular/core';\nimport { TranslateService, TranslateParams } from '@ngstack/translate';\n\n@Pipe({\n  name: 'myTranslate',\n  pure: false\n})\nexport class CustomTranslatePipe implements PipeTransform {\n  constructor(private translate: TranslateService) {}\n\n  transform(key: string, params?: TranslateParams): string {\n    return this.translate.get(key, params);\n  }\n}\n```\n\nThen in the HTML templates you can use your pipe like following:\n\n```html\n\u003cp\u003e\n  Custom Pipe: {{ 'TITLE' | myTranslate }}\n\u003c/p\u003e\n```\n\n### Lazy Loading\n\nTo enable Lazy Loading\nuse `TranslateModule.forRoot()` in the main application,\nand `TranslateModule.forChild()` in all lazy-loaded feature modules.\n\nFor more details please refer to [Lazy Loading Feature Modules](https://angular.io/guide/lazy-loading-ngmodules)\n\n## See also\n\nList of alternative libraries you can check out:\n\n- [ngneat/transloco](https://github.com/ngneat/transloco)\n- [ngx-translate/core](https://github.com/ngx-translate/core)\n","funding_links":["https://github.com/sponsors/DenysVuika","https://www.buymeacoffee.com/denys"],"categories":["Table of contents"],"sub_categories":["Angular"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngstack%2Ftranslate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fngstack%2Ftranslate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngstack%2Ftranslate/lists"}