--- createdAt: 2025-09-09 updatedAt: 2026-09-27 priority: 9 title: "NestJS i18n - Complete guide to translate your app" description: "Set up Intlayer in NestJS: detect the locale per request, translate controller responses and validation messages, typed end to end." keywords: - Internationalization - Documentation - Intlayer - NestJS - JavaScript - Backend slugs: - doc - environment - nest history: - version: 8.9.0 date: 2026-05-04 changes: "Update Solid useIntlayer API usage to direct property access" - version: 7.5.9 date: 2025-12-30 changes: "Add init command" - version: 5.8.0 date: 2025-09-09 changes: "Initial doc" author: aymericzip --- # Translate your Nest backend website using Intlayer `express-intlayer` is a powerful internationalization (i18n) middleware for Express applications, designed to make your backend services globally accessible by providing localized responses based on the client's preferences. Since NestJS is built on top of Express, you can seamlessly integrate `express-intlayer` into your NestJS applications to handle multilingual content effectively. tical Use Cases - **Displaying Backend Errors in User's Language**: When an error occurs, displaying messages in the user's native language improves understanding and reduces frustration. This is especially useful for dynamic error messages that might be shown in front-end components like toasts or modals. - **Retrieving Multilingual Content**: For applications pulling content from a database, internationalization ensures that you can serve this content in multiple languages. This is crucial for platforms like e-commerce sites or content management systems that need to display product descriptions, articles, and other content in the language preferred by the user. - **Sending Multilingual Emails**: Whether it's transactional emails, marketing campaigns, or notifications, sending emails in the recipient’s language can significantly increase engagement and effectiveness. - **Multilingual Push Notifications**: For mobile applications, sending push notifications in a user's preferred language can enhance interaction and retention. This personal touch can make notifications feel more relevant and actionable. - **Other Communications**: Any form of communication from the backend, such as SMS messages, system alerts, or user interface updates, benefits from being in the user's language, ensuring clarity and enhancing the overall user experience. By internationalizing the backend, your application not only respects cultural differences but also aligns better with global market needs, making it a key step in scaling your services worldwide. ## Getting Started ### Create a new NestJS Project ```bash packageManager="npm" npm install -g @nestjs/cli nest new my-nest-app ``` ### Installation To begin using `express-intlayer`, install the package using npm: ```bash packageManager="npm" npx intlayer init --interactive ``` ```bash packageManager="pnpm" pnpm dlx intlayer init --interactive ``` ```bash packageManager="yarn" yarn dlx intlayer init --interactive ``` ```bash packageManager="bun" bunx intlayer init --interactive ``` > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent. > This command will detect your environment and install the required packages. For example: ```bash packageManager="npm" npm install intlayer express-intlayer ``` ```bash packageManager="pnpm" pnpm add intlayer express-intlayer ``` ```bash packageManager="yarn" yarn add intlayer express-intlayer ``` ```bash packageManager="bun" bun add intlayer express-intlayer ``` ### Configure tsconfig.json In order to use Intlayer with TypeScript, ensure your `tsconfig.json` is set up to support ES modules. You can do this by setting the `module` and `moduleResolution` options to `nodenext`. ```json5 fileName="tsconfig.json" { compilerOptions: { module: "nodenext", moduleResolution: "nodenext", // ... other options }, } ``` ### Setup Configure the internationalization settings by creating an `intlayer.config.ts` in your project root: ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]} import { Locales, type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, }, }; export default config; ``` ### Declare Your Content Create and manage your content declarations to store translations: ```typescript fileName="src/app.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"] import { t, type Dictionary } from "intlayer"; const appContent: Dictionary = { key: "app", content: { greet: t({ en: "Hello World!", fr: "Bonjour le monde !", es: "¡Hola Mundo!", }), }, }; export default appContent; ``` > Your content declarations can be defined anywhere in your application as soon as they are included into 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](/doc/concept/content). ### Express Middleware Setup Integrate the `express-intlayer` middleware into your NestJS application to handle internationalization: ```typescript fileName="src/app.module.ts" codeFormat="typescript" import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common"; import { AppController } from "./app.controller"; import { AppService } from "./app.service"; import { intlayer } from "express-intlayer"; @Module({ imports: [], controllers: [AppController], providers: [AppService], }) export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer.apply(intlayer()).forRoutes("*"); // Apply to all routes } } ``` ### Use Translations in Your Services or Controllers You can now use the `getIntlayer` function to access translations in your services or controllers: ```typescript fileName="src/app.service.ts" codeFormat="typescript" import { Injectable } from "@nestjs/common"; import { getIntlayer } from "express-intlayer"; @Injectable() export class AppService { getHello(): string { return getIntlayer("app").greet; } } ``` ### Compatibility `express-intlayer` is fully compatible with: - [`react-intlayer`](/doc/packages/react-intlayer) - [`next-intlayer`](/doc/packages/next-intlayer) - [`vite-intlayer`](/doc/packages/vite-intlayer) It also works seamlessly with any internationalization solution across various environments, including browsers and API requests. You can customize the middleware to detect locale through headers or cookies: ```typescript fileName="intlayer.config.ts" codeFormat="typescript" import { Locales, type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { // ... Other configuration options routing: { storage: [ { type: "header", name: "my-locale-header" }, { type: "cookie", name: "my-locale-cookie" }, ], }, }; export default config; ``` By default, `express-intlayer` will interpret the `Accept-Language` header to determine the client's preferred language. > For more information on configuration and advanced topics, visit our [documentation](/doc/concept/configuration). ### Configure TypeScript `express-intlayer` leverages the robust capabilities of TypeScript to enhance the internationalization process. TypeScript's static typing ensures that every translation key is accounted for, reducing the risk of missing translations and improving maintainability. ![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true) ![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.webp?raw=true) Ensure the autogenerated types (by default at ./types/intlayer.d.ts) are included in your tsconfig.json file. ```json5 fileName="tsconfig.json" { // ... Your existing TypeScript configurations include: [ // ... Your existing TypeScript configurations ".intlayer/**/*.ts", // Include the auto-generated types ], } ``` ### VS Code Extension To improve your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**. - [Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension) 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md). - [Intlayer VS Code Extension documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md) ### 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: ```plaintext fileName=".gitignore" # Ignore the files generated by Intlayer .intlayer ``` ## Frequently Asked Questions NestJS has `nestjs-i18n`, which is the common choice and covers JSON or YAML catalogs with a request scoped service. The alternative is `Intlayer` through `express-intlayer`, which uses the same declared content as your frontend, is typed against your dictionaries, and comes with AI translation and a CMS. The reason to internationalize the backend at all is that a large part of the text a user reads never passes through the frontend: API error messages, transactional emails, push notifications, SMS and PDF exports. Those need the recipient's language, resolved per request rather than per session. See [why Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/interest_of_intlayer.md). - [why Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/interest_of_intlayer.md) Very little. Dictionaries are compiled ahead of time and only the locales you declare are included, so there is no catalog loading at boot and no file reads on the request path. That matters most on serverless and edge deployments, where the bundle size drives cold start time. See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md). - [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) Yes, and there are two paths. You can migrate the content progressively with the [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_i18next_to_intlayer.md). Or you can keep your current API entirely: the [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md) expose the exact same API as `i18next`, but served by Intlayer dictionaries, so imports change and handler code does not. - [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_i18next_to_intlayer.md) - [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md) Yes. The [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md) keeps your `/messages/{locale}/{namespace}.json` files as the source of truth and generates Intlayer dictionaries from them, in both directions. A [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-po.md) does the same for gettext catalogs, and [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/per_locale_file.md) let you split content by language instead of grouping locales in one file. - [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md) - [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-po.md) - [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/per_locale_file.md) No. Run `npx intlayer extract` and Intlayer reads your source files, pulls the user facing strings out and writes a `.content` file next to each one, so you review a diff instead of copying strings into a catalog one at a time. See the [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/extract.md). - [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/extract.md) On the frontend side of the same project, the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compiler.md) goes further and generates the dictionaries at build time from your JSX, TSX, Vue or Svelte source, so the two halves of the app share one content layer with no keys maintained by hand. - [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compiler.md) Five pieces, all optional: - **[VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md)**: jump from a `useIntlayer` key to the content file that declares it, extract content from a component, and run build, fill, test, push and pull from the command palette or a dedicated Intlayer tab. - **[LSP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**: the same awareness in any editor that speaks LSP, with go to definition, find all references, hover previews of a translated value, autocompletion of keys and fields, and a warning when a key is not declared anywhere. It also resolves `i18next`, `react-i18next`, `next-intl` and `use-intl` calls, which helps while you migrate. - **[MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**: exposes the Intlayer documentation and CLI to Cursor, VS Code, Claude Desktop, Claude Code and ChatGPT, so an assistant answers from current docs instead of guessing, and can run commands such as `intlayer fill` itself. - **[Agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**: focused skills such as `intlayer-config`, `intlayer-cli` and `intlayer-content`, plus one per framework, that teach an agent your routing setup and the content node types. - **[ESLint plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/eslint.md)**: `no-raw-text` flags hardcoded strings, with further rules for static dictionary keys and unused content. By default `express-intlayer` reads the `Accept-Language` header of the incoming request and picks the closest declared locale, falling back to your default locale. You can change the source with `routing.storage`, for example a custom header or a cookie set by your frontend, so the API answers in the language the user actually selected rather than the one their browser advertises. See the [configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md). - [configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md) Yes. The middleware scopes the active locale to the request, so two concurrent requests in different languages never read each other's locale. That is what makes `t()` and `getIntlayer()` safe to call from a service without threading a locale argument through every function. Declare the email content in a content file like any other content, then resolve it with `getIntlayer` for the recipient's stored locale instead of the request locale. This matters for jobs and queues, where the language belongs to the user record and there is no incoming request to read a header from. Wrap the message in `t()` at the point where the error is built. The active request locale resolves it, so the client receives a message it can display directly, and your frontend does not need a parallel catalog of error codes. Yes. Call `getIntlayer("app")` inside the service or controller, as shown above. There is no module to register per feature and no token to inject, because the active locale comes from the request context that the middleware installed. Run `npx intlayer fill`, which fills missing translations with the LLM of your choice using your own provider and API key. Add `--git-diff` to translate only the content changed on the branch. See the [fill command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/fill.md) and [CI/CD integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/CI_CD.md). - [fill command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/fill.md) - [CI/CD integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/CI_CD.md) Yes: [plural forms](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/plurial.md), [gender based content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/gender.md), conditions, [insertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion.md) for interpolated values, [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown.md) for email bodies, and [formatters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/formatters.md) for numbers, dates and currencies. - [plural forms](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/plurial.md) - [gender based content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/gender.md) - [insertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion.md) - [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown.md) - [formatters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/formatters.md) Yes. Intlayer generates the types of your dictionaries into `./types/intlayer.d.ts`, so a key that does not exist is a compile error rather than an empty string at runtime. Run `npx intlayer test` in CI to fail the build when a declared locale is missing content. Yes, and that is the usual setup. `express-intlayer` works alongside `react-intlayer`, `next-intlayer` and `vite-intlayer` on the same declared content, so a label used both in an API response and in a page is declared once. See [how Intlayer works](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/how_works_intlayer.md). - [how Intlayer works](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/how_works_intlayer.md) Yes, under the Apache 2.0 license, commercial use included. The hosted [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) is an optional paid service that can also be [self hosted](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/self_hosting.md). - [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) - [self hosted](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/self_hosting.md)