@hug/ngx-g11n

Angular helpers for internationalizing and localizing your application

Getting started

To set up or update an Angular project with this library use the Angular CLI's [schematic][schematics] commands:

#### Installation

``sh
ng add @hug/ngx-g11n
`

#### Update

`sh
ng update @hug/ngx-g11n
`

Usage

This library uses the official [@angular/localize][angular-localize-url] package under the hood, so manage your translations just as you would with it.

Then use the command ng extract-i18n to extract the marked messages from your components into a single source language file.

#### Examples

`html

Message to translate
`

`html

...
`

`html

{items.length, plural, =0 {No item} =1 {1 item} other {{{items.length}} items}}
`

`ts
// Script
const msgToTranslate = $localize:@@demoText:Message to translate;
`

Helpers

The following helpers are available.

#### # currentLanguage

Get the current language of the application.

`ts
// import { currentLanguage } from '@hug/ngx-g11n/legacy'; / for ng14 apps /
import { currentLanguage } from '@hug/ngx-g11n';

console.log(currentLanguage());
`

#### # setLanguage

Set a language and reload the application.

`ts
// import { setLanguage } from '@hug/ngx-g11n/legacy'; / for ng14 apps /
import { setLanguage } from '@hug/ngx-g11n';

setLanguage('en-US');
`

Options

The behavior of the library can be configured either in:

app.config.ts (if the app is a standalone Angular application)*

`ts
// import { provideG11n } from '@hug/ngx-g11n/legacy'; / for ng14 apps /
import { provideG11n } from '@hug/ngx-g11n';

export const appConfig: ApplicationConfig = {
providers: [
provideG11n(...features)
]
};
`

app-module.ts (if the app is not a standalone Angular application)*

`ts
// import { G11nModule } from '@hug/ngx-g11n/legacy'; / for ng14 apps /
import { G11nModule } from '@hug/ngx-g11n';

@NgModule({
imports: [
G11nModule.forRoot(...features)
]
})
export class AppModule { }
`

The following features are available:

#### # withDefaultLocales

This feature will configure the library with fr-CH and de-CH as the default locales.

If you are not using [Angular Material][angular-material-url] or prefer to use any other locale, please refer to the withLocales feature.

`ts
import { withDefaultLocales } from '@hug/ngx-g11n/locales';

provideG11n(withDefaultLocales())
`

#### # withLocales

This feature will configure the library with the given locales.

The extra, datefns and translationFilename parameters are optionals and based on your personal requirements.

`ts
// import { withLocales } from '@hug/ngx-g11n/legacy'; / for ng14 apps /
import { withLocales } from '@hug/ngx-g11n';

provideG11n(withLocales({
'fr-CH': {
base: () => import('@angular/common/locales/fr-CH'),
extra: () => import('@angular/common/locales/extra/fr-CH'),
datefns: () => import('date-fns/locale/fr-CH'),
translationFilename: 'fr.json'
}
}))
`

#### # withDateFnsMaterial

This feature will configure the library with everything that's required for [Angular Material][angular-material-url].

As the name suggests, it will also use the [datefns][datefns-url] adapter.

`ts
import { withDateFnsMaterial } from '@hug/ngx-g11n/material';

provideG11n(withDateFnsMaterial())
`

#### # withInterceptor

This feature will configure the library with an http interceptor.

Accept-Language: xyz will be added to the header of every http requests.

`ts
// import { withInterceptor } from '@hug/ngx-g11n/legacy'; / for ng14 apps /
import { withInterceptor } from '@hug/ngx-g11n';

provideG11n(withInterceptor())
`

#### # withOptions

This feature will override the defaults library options.

`ts
// import { withOptions } from '@hug/ngx-g11n/legacy'; / for ng14 apps /
import { withOptions } from '@hug/ngx-g11n';

interface G11nOptions {
/* @default 'fr-CH' /
defaultLanguage?: string;
/* @default 'CHF' /
defaultCurrency?: string;
/* @default true /
useNavigatorLanguage?: boolean;
/* @default false /
loadLocaleExtra?: boolean;
/* @default true /
useTranslations?: boolean;
/* @default '/translations' ('/assets/translations' for legacy apps) /
translationsPath?: string;
/* @default 'lang' /
queryParamName?: string;
/* @default localStorage /
storage?: Storage;
/* @default NO_DEBUG /
debug?: G11nDebug;
}

provideG11n(withOptions(options))
`

Heuristic

The language to use is determined according to the following priorities, in order:

1. Query parameter in the URL
2. Browser storage
3. Browser language
4. Library setting

And if a language is found using the above criteria:

1. Check for an exact match in the locales provided to the library (e.g., 'en-US')
2. Check for a match on the base language only (e.g., 'en')
3. Check for a match on the base language with any region (e.g., 'en-GB')

Debug

The following modes are available:

#### # SHOW_KEYS

Will display each translation key next to its translation (ex: "message (@key)").

Useful when you need to quickly and easily retrieve the associated key of a message.

> Use withOptions({ debug: G11nDebug.SHOW_KEYS })) or the query parameter (ex: ?lang=keys).

#### # DUMMY_TRANSLATIONS

Will replace every translation with a dash (-).

Useful when you need to see what messages are left untranslated.

> Use withOptions({ debug: G11nDebug.DUMMY_TRANSLATIONS })) or the query parameter (ex: ?lang=dummy).

#### # NO_DEBUG

Disable any debug mode.

> Use withOptions({ debug: G11nDebug.NO_DEBUG })`.

Development

See the [developer docs][developer].

Contributing

#### > Want to Help?

Want to file a bug, contribute some code or improve documentation? Excellent!

But please read up first on the guidelines for [contributing][contributing], and learn about submission process, coding rules and more.

#### > Code of Conduct

Please read and follow the [Code of Conduct][codeofconduct], and help us keep this project open and inclusive.

Credits

Copyright (C) 2025 [HUG - Hôpitaux Universitaires Genève][dsi-hug]

![love@hug][dsi-hug]

[schematics]: https://angular.io/guide/schematics-for-libraries
[angular-localize-url]: https://angular.dev/guide/i18n#learn-about-angular-internationalization
[angular-material-url]: https://material.angular.io
[datefns-url]: https://material.angular.io/components/datepicker/overview#choosing-a-date-implementation-and-date-format-settings
[developer]: https://github.com/dsi-hug/ngx-g11n/blob/main/DEVELOPER.md
[contributing]: https://github.com/dsi-hug/ngx-g11n/blob/main/CONTRIBUTING.md
[codeofconduct]: https://github.com/dsi-hug/ngx-g11n/blob/main/CODE_OF_CONDUCT.md
[dsi-hug]: https://github.com/dsi-hug