express-intlayer
Version:
Manage internationalization i18n in a simple way for express application.
256 lines (187 loc) • 9.03 kB
Markdown
<div align="center">
<a href="https://intlayer.org">
<img src="https://raw.githubusercontent.com/aymericzip/intlayer/572ae9c9acafb74307b81530c1931a8e98990aef/docs/assets/logo.png" width="500" alt="intlayer" />
</a>
</div>
<div align="center">
<a href="https://www.npmjs.com/package/express-intlayer">
<img alt="npm" src="https://img.shields.io/npm/v/express-intlayer.svg?labelColor=49516F&color=8994BC" />
</a>
<a href="https://npmjs.org/package/express-intlayer">
<img alt="downloads" src="https://badgen.net/npm/dm/express-intlayer?labelColor=49516F&color=8994BC" />
</a>
<a href="https://npmjs.org/package/express-intlayer">
<img alt="types included" src="https://badgen.net/npm/types/express-intlayer?labelColor=49516F&color=8994BC"
/>
</div>
# express-intlayer: JavaScript Package to internationalize (i18n) an Express.js application
**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, Next.js, and Express.js.
**The `express-intlayer` package** allows you to internationalize your Express.js application. It provides a middleware to detect the user's preferred locale, and returns the appropriate dictionary for the user.
## Why Internationalize Your Backend?
Internationalizing your backend is essential for serving a global audience effectively. It allows your application to deliver content and messages in the preferred language of each user. This capability enhances user experience and broadens your application's reach by making it more accessible and relevant to people from different linguistic backgrounds.
### Practical 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.
## Why to integrate Intlayer?
- **Type-Safe Environment**: Leverage TypeScript to ensure all your content definitions are precise and error-free.
## Installation
Install the necessary package using your preferred package manager:
```bash
npm install express-intlayer
```
```bash
yarn add express-intlayer
```
```bash
pnpm add express-intlayer
```
### Configure Intlayer
Intlayer provides a configuration file to set up your project. Place this file in the root of your project.
```typescript fileName="intlayer.config.ts" codeFormat="typescript"
import { Locales, type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
defaultLocale: Locales.ENGLISH,
},
};
export default config;
```
```javascript fileName="intlayer.config.mjs" codeFormat="esm"
import { Locales } from "intlayer";
/** @type {import('intlayer').IntlayerConfig} */
const config = {
internationalization: {
locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
defaultLocale: Locales.ENGLISH,
},
};
export default config;
```
```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
const { Locales } = require("intlayer");
/** @type {import('intlayer').IntlayerConfig} */
const config = {
internationalization: {
locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
defaultLocale: Locales.ENGLISH,
},
};
module.exports = config;
```
> For a complete list of available parameters, refer to the [configuration documentation](https://intlayer.org/doc/concept/configuration).
## Example of usage
Setup your Express application to use `express-intlayer`:
```typescript fileName="src/index.ts" codeFormat="typescript"
import express, { type Express } from "express";
import { intlayer, t } from "express-intlayer";
const app: Express = express();
// Load internationalization request handler
app.use(intlayer());
// Routes
app.get("/", (_req, res) => {
res.send(
t({
en: "Example of returned content in English",
fr: "Exemple de contenu renvoyé en français",
"es-ES": "Ejemplo de contenido devuelto en español (España)",
"es-MX": "Ejemplo de contenido devuelto en español (México)",
})
);
});
// Start server
app.listen(3000, () => console.log(`Listening on port 3000`));
```
```javascript fileName="src/index.mjs" codeFormat="esm"
import express from "express";
import { intlayer, t } from "express-intlayer";
const app = express();
// Load internationalization request handler
app.use(intlayer());
// Routes
app.get("/", (_req, res) => {
res.send(
t({
en: "Example of returned content in English",
fr: "Exemple de contenu renvoyé en français",
"es-MX": "Ejemplo de contenido devuelto en español (México)",
"es-ES": "Ejemplo de contenido devuelto en español (España)",
})
);
});
// Start server
app.listen(3000, () => console.log(`Listening on port 3000`));
```
```javascript fileName="src/index.cjs" codeFormat="commonjs"
const express = require("express");
const { intlayer, t } = require("express-intlayer");
const app = express();
// Load internationalization request handler
app.use(intlayer());
// Routes
app.get("/", (_req, res) => {
res.send(
t({
en: "Example of returned content in English",
fr: "Exemple de contenu renvoyé en français",
"es-MX": "Ejemplo de contenido devuelto en español (México)",
"es-ES": "Ejemplo de contenido devuelto en español (España)",
})
);
});
// Start server
app.listen(3000, () => console.log(`Listening on port 3000`));
```
### Compatibility
`express-intlayer` is fully compatible with:
- [`react-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/react-intlayer/index.md) for React applications
- [`next-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/next-intlayer/index.md) for Next.js applications
- [`vite-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/vite-intlayer/index.md) for Vite applications
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
middleware: {
headerName: "my-locale-header",
cookieName: "my-locale-cookie",
},
};
export default config;
```
```javascript fileName="intlayer.config.mjs" codeFormat="esm"
import { Locales } from "intlayer";
/** @type {import('intlayer').IntlayerConfig} */
const config = {
// ... Other configuration options
middleware: {
headerName: "my-locale-header",
cookieName: "my-locale-cookie",
},
};
export default config;
```
```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
const { Locales } = require("intlayer");
/** @type {import('intlayer').IntlayerConfig} */
const config = {
// ... Other configuration options
middleware: {
headerName: "my-locale-header",
cookieName: "my-locale-cookie",
},
};
module.exports = config;
```
By default, `express-intlayer` will interpret the `Accept-Language` header to determine the client's preferred language.
## Functions provided by `express-intlayer` package
- [`t()`](https://intlayer.org/doc/packages/express-intlayer/t)
## Read about Intlayer
- [Intlayer Website](https://intlayer.org)
- [Intlayer Documentation](https://intlayer.org/docs)
- [Intlayer GitHub](https://github.com/aymericzip/intlayer)
- [Ask your questions to our smart documentation](https://intlayer.org/docs/chat)