Translate your Angular 21 (Vite) website using Intlayer | Internationalisation (i18n)

Table of contents

Why Intlayer over alternatives?

Compared to main solutions like ngx-translate or angular-l10n, Intlayer is a solution that comes with integrated optimizations such as:

Step-by-Step Guide to Setting Up Intlayer in an Angular Application

See the Application Template on GitHub.

1. 1

   Install Dependencies

   Install the necessary packages using npm:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

   • intlayer

     The core package providing internationalisation tools for configuration management, translation, content declaration, transpilation, and CLI commands.

   • angular-intlayer The package that integrates Intlayer with the Angular application. It provides context providers and hooks for Angular internationalisation.

   • @angular-builders/custom-esbuild Required to customise the esbuild configuration of the Angular CLI.

2. 2

   Configuration of your project

   Create a configuration file to configure your application's languages:

   intlayer.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Your other languages
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Through this configuration file, you can set up localised URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the configuration documentation.

3. 3

   Integrate Intlayer in Your Angular Configuration

   To integrate Intlayer with the Angular CLI, you need to use a custom builder. This guide assumes you are using Vite/esbuild (default for Angular 21 projects).

   First, modify your angular.json to use the custom esbuild builder. Update the build and serve configurations:

   angular.json

   Copy content

   Copy code

   Copy the code to the clipboard

   {  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"          "options": {            "define": {              "process.env": "{}",            },            "plugins": ["./esbuild.plugins.ts"],            "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"          "options": {            "prebundle": {              "exclude": [                "intlayer",                "angular-intlayer",                "@intlayer/config/built",                "@intlayer/core"              ]          },        },      },    },  },}

   Ensure you replace your-app-name with your project's actual name in the angular.json.

   Next, create an esbuild.plugins.ts file in the root of your project:

   esbuild.plugins.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

   The intlayerEsbuildPlugin function configures esbuild with Intlayer. It injects the plugin to handle content declaration files and sets up configurations for optimal performance.

   NX users: NX's Angular builders load plugin files via Node's native ESM resolution and do not compile TypeScript plugin files on the fly. Use a .mjs file instead and update the plugins reference in angular.json accordingly:

   esbuild.plugins.mjs

   Copy content

   Copy code

   Copy the code to the clipboard

   import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

   Then in angular.json point to "./esbuild.plugins.mjs" instead of "./esbuild.plugins.ts".

4. 4

   Declare Your Content

   Create and manage your content declarations to store translations:

   Your content declarations can be defined anywhere in your application as long as they are included in the contentDir directory (by default, ./src). And match the content declaration file extension (by default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   For more details, refer to the content declaration documentation.

5. 5

   Utilise Intlayer in Your Code

   To utilise Intlayer's internationalisation features throughout your Angular application, you need to provide Intlayer in your application configuration.

   src/app/app.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { provideIntlayer } from "angular-intlayer";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    provideIntlayer(), // Add the Intlayer provider here  ],};

   Then, you can use the useIntlayer function within any component.

   src/app/app.component.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

   And in your template:

   src/app/app.component.html

   Copy content

   Copy code

   Copy the code to the clipboard

   <div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

   The Intlayer content is returned as a Signal, so you access the values by calling the signal: content().title.

6. 6

   Change the language of your content

   Optional

   To change the language of your content, you can use the setLocale function provided by the useLocale function. This allows you to set the application's locale and update the content accordingly.

   Create a component to switch between languages:

   src/app/locale-switcher.component.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

   Then, use this component in your app.component.ts:

   src/app/app.component.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Configure TypeScript

Intlayer uses Module Augmentation to get the benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types.

{  // ... Your existing TypeScript configurations  "include": [    // ... Your existing TypeScript configurations    ".intlayer/**/*.ts", // Include the autogenerated types  ],}

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

# Ignore files generated by Intlayer.intlayer

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

To go further, you can implement the visual editor or externalise your content using the CMS.