https://github.com/adamcsk1/ngx-signal-translate
A signal-driven translation service.
https://github.com/adamcsk1/ngx-signal-translate
angular
Last synced: 2 months ago
JSON representation
A signal-driven translation service.
- Host: GitHub
- URL: https://github.com/adamcsk1/ngx-signal-translate
- Owner: adamcsk1
- License: mit
- Created: 2024-07-10T09:37:56.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-26T08:58:58.000Z (11 months ago)
- Last Synced: 2024-11-26T09:34:39.513Z (11 months ago)
- Topics: angular
- Language: TypeScript
- Homepage:
- Size: 744 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-angular - ngx-signal-translate - A signal-driven translation service. (Development Utilities / Internationalization)
- awesome-angular - ngx-signal-translate - A signal-driven translation service. (Development Utilities / Internationalization)
README
# NgxSignalTranslate
A signal-driven translation service.
## Compatibility with Angular Versions
ngx-signal-translate
Angular
3.x
>= 20.x.x
2.x
19.x.x
1.x
18.x.x
## Table of contents
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Language file](#a-language-file)
- [Params in the language file](#params-in-the-language-file)
- [Usage](#usage)
- [Component template](#component-template)
- [Typescript files](#typescript-files)
## Features
* Lazy load language JSON files via HTTP request.
* Pipe for translating the template strings. _(signal)_
* Service with a synchronous, signal and observable translate interface. *(The synchronous interface works with computed signal and signal effects.)*
* Option for the variable replace in the translated strings.
## Installation
```bash
npm install ngx-signal-translate
# Or if you use yarn
yarn add ngx-signal-translate
```
### Configuration
Add configuration provider to your app.config.ts as provider.
```ts
import { provideSignalTranslateConfig } from 'ngx-signal-translate';
export const appConfig: ApplicationConfig = {
providers: [
provideSignalTranslateConfig({path: ''}),
],
};
```
The path is a required config parameter, that will be the json language files base folder.
And finally set the default language in your AppComponent constructor:
```ts
import { NgxSignalTranslateService } from 'ngx-signal-translate';
@Component({})
export class AppComponent {
readonly #signalTranslateService = inject(NgxSignalTranslateService);
constructor(){
this.#signalTranslateService.setLanguage('en');
}
}
```
## A language file
The language files should be JSON files, and the language key should be the file name.
Example:
```json
{
"DEMO": "Demo"
}
```
## Params in the language file
The language files be able to handle variables in the translation string. When the translation service gets variables for a replacement, it will try to replace these keys in the template string.
*You need to put the variable key inside brackets.*
Example:
```json
{
"DEMO": "Demo {param}"
}
```
## Usage
### Component template
```ts
import { NgxSignalTranslatePipe } from 'ngx-signal-translate';
@Component({
imports: [NgxSignalTranslatePipe]
})
export class DemoComponent {}
```
without params:
```html
{{('Demo' | signalTranslate)()}}
```
with params:
```html
{{('Demo' | signalTranslate : {param: 'hello'})()}}
```
### Typescript files
```ts
import { NgxSignalTranslateService } from 'ngx-signal-translate';
@Component({})
export class DemoComponent implements ngOnInit{
readonly #signalTranslateService = inject(NgxSignalTranslateService);
readonly #translatedText = computed(() => this.#signalTranslateService.translate('DEMO'));
constructor() {
effect(() => {
console.log(this.#signalTranslateService.translate('DEMO'));
});
/* The translate function triggers the signal effects. */
}
public ngOnInit(): void {
console.log(this.#signalTranslateService.translate('DEMO'));
/* If the selected language files were not loaded, then the function will return with the translation key. */
this.#signalTranslateService.translate$('DEMO').subscribe(console.log);
/* The translate$ observable will wait for the language file to load. */
console.log(this.#translatedText());
/* The translate function works with computed signals. That will trigger the value refresh when the language resource / selected language changed. */
}
}
```
The second parameter can be used to pass translate variables to the _translate_ and _translate$_ function.