@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 commands:

Installation

ng add @hug/ngx-g11n

More details

The ng add command will ask you the following questions:

1. ? Default language: the default language used by your application
2. ? Default currency: the default currency used by your application
3. ? Use navigator language: whether to use the navigator language
4. ? Use Angular locale extra: whether to also register Angular locale extra
5. ? Translations path: the path to your translation files
6. ? Query param name: the name of the query parameter used to define the language
7. ? Auto-inject locale in request headers: whether to inject the language in every requests header
8. ? Add support for Angular Material: whether to also configure things for Angular Material
9. ? Add locales [fr-CH, de-CH] by defaults: whether to add fr-CH and de-CH by default

And based on your answers, it will also potentialy perform the following actions:

• Run ng add @angular/localize schematic
• Install @angular/material-date-fns-adapter as a dev dependency
• Deploy default language files in either /public or /src/assets folder
• Add skipLibCheck in angularCompilerOptions of your tsconfig.json file (for ng14 apps)
• Add or modify the required configurations in your angular.json file:

  "projects": {
    "my-app": {
      "i18n" {
        "sourceLocale": "fr-CH"
      },
      "architect": {
        "build": {
          "options": {
            "i18nMissingTranslation": "error"
          }
        },
        "extract-i18n": {
          "builder": "@angular/build:extract-i18n",
          "options": {
            "outputPath": "projects/demo-app/public/i18n",
            "outFile": "fr-CH.json",
            "format": "json"
          }
        }
      }
    }
  }

• Provide and configure the library

Update

ng update @hug/ngx-g11n

Usage

This library uses the official @angular/localize 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

<!-- Template content -->
<span i18n="@@demoText">Message to translate</span>

<!-- Template attribute -->
<span subtitle="Message to translate" i18n-subtitle="@@demoText">...</span>

<!-- Template ICU -->
<span i18n="@@demoPluralText">{items.length, plural, =0 {No item} =1 {1 item} other {{{items.length}} items}}</span>

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

Helpers

The following helpers are available.

# currentLanguage

Get the current language of the application.

// 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.

// 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)

// 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)

// 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 or prefer to use any other locale, please refer to the withLocales feature.

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.

// 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.

As the name suggests, it will also use the datefns adapter.

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.

// 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.

// 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.

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, and learn about submission process, coding rules and more.

> Code of Conduct

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

Credits

Copyright (C) 2025 HUG - Hôpitaux Universitaires Genève