# ng-gettext

> Gettext implementation for angular.

Latest version **1.1.1** (published 2021-10-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install ng-gettext
pnpm add ng-gettext
yarn add ng-gettext
bun add ng-gettext
```

Provides the command `gettext-build-translations`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2021-10-20 |
| First published | 2021-09-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 124.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | bushee |

## Links

- npm: https://www.npmjs.com/package/ng-gettext
- Repository: https://github.com/bushee/ng-gettext
- Homepage: https://github.com/bushee/ng-gettext#readme
- Issues: https://github.com/bushee/ng-gettext/issues
- npm.io page: https://npm.io/package/ng-gettext

## Dependencies (2)

- [yargs](https://npm.io/package/yargs.md) 17.1.1
- [pofile](https://npm.io/package/pofile.md) 1.1.1

## Recent versions

- 1.1.1 (latest) — 2021-10-20
- 1.1.0 — 2021-09-21
- 1.0.7 — 2021-09-21
- 1.0.6 — 2021-09-20
- 1.0.5 — 2021-09-09
- 1.0.4 — 2021-09-09
- 1.0.3 — 2021-09-09
- 1.0.2 — 2021-09-09
- 1.0.1 — 2021-09-09
- 1.0.0 — 2021-09-09

## README

# ng-gettext

This library utilizes gettext mechanism in angular.

It is strongly inspired by [`angular-gettext`](https://www.npmjs.com/package/angular-gettext) angularjs implementation and utilises .po file parser created by its author, [Ruben Vermeersch](https://www.npmjs.com/~rubenv).

## Limitations
For now, pluralization and contexts are not implemented.

## Usage

### Module
You may simply import `GettextModule` into your angular application.

If you wish to initialize translations cache before any unit uses it, just feed `GettextService` with `TranslationsCache` on module construction:

```typescript
import { NgModule } from '@angular/core';
import { GettextModule, GettextService } from 'ng-gettext';
import translationsCache from './translations-cache';

@NgModule({
    imports: [GettextModule]
})
export class MyModule {
    public constructor(gettextService: GettextService) {
        gettextService.setTranslations(translationsCache);
    }
}
```
                               `
#### Preparing translations cache
Use `node_modules/.bin/gettext-build-translations` script to compile cache from your `.po` files.

Arguments:
- `--input directory` - path (cwd-relative or absolute) to directory containing `.po` files. May be passed multiple times.
- `--output file` - path to file to be generated. This will be a `.ts` file containing a default export of type `TranslationsCache`.

### Component
`<gettext-translate>` component is provided. It has following arguments:
- `key` - translation key
- `interpolations` - _(optional)_ key-value map of values to replace interpolated parts of translation with; by default, `[[variable]]` marks a part of translation to be interpolated by `interpolations.variable` value

#### Example
```html
<!-- no interpolation -->
<gettext-translate key="You've got a message"></gettext-translate> <!-- simply translates "You've got a message" -->
<gettext-translate [key]="'Message text ' + id"></gettext-translate> <!-- takes resolved string, e.g. "Message text 1" as translation key -->

<!-- interpolation -->
<gettext-translate key="You've got [[number]] messages" [interpolations]="{number: 3}"></gettext-translate> <!-- interpolates "3" into translated "You've got [[number]] messages" text -->
```

### Pipe
`gettextTranslate` pipe is provided. It uses input string as translation key. It has the same optional arguments as component.

#### Example
```html
{{ 'You\'ve got a message' | gettextTranslate }} <!-- simply translates "You've got a message" -->
{{ 'You've got [[number]] messages' | gettextTranslate:{number: 3} }} <!-- interpolates "3" into translated "You've got [[number]] messages" text -->
```

### Service
`GettextService` service is provided. It includes some all translation as well as configuration routines:

- `setDebugMode(enable: boolean, prefix?: string, suffix?: string): void`

    Allows to enable/disable debug mode in which missing translation keys are surrounded by prefix and suffix. Default prefix is `[MISSING] `; default suffix is empty.

    This is helpful to notice missing translations while running application in development mode - especially when enabled during its bootstrap phase.

- `setInterpolationMarkers(prefix: string, suffix: string): void`

    Allows to change default `[[`/`]]` interpolation markers for your convenience.

- `getString(key: string, interpolations?: Record<string, any>): string`

    Allows to translate passed key in non-template scope. Optional interpolations key-value map may be passed - see component documentation for more details.

- `getCurrentLanguage(): string`

    Returns current language setting.

- `setCurrentLanguage(language: string): void`

    Changes current language setting.

- `setTranslations(language: string, translations: Record<string, string>): void`

    Adds translations to given language. `translations` is key-translation map.

    Any translations passed are **appended** to current translations cache, so there's no problem to run this method multiple times to feed from different sources. If key collision occurs, the newest value is used.

## Requirements
- angular ^8.0.0

---
_Source: https://npm.io/package/ng-gettext · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._