Tài liệu Plugin intlayer cho Elysia

Plugin intlayer cho Elysia phát hiện locale của người dùng và tiêm một đối tượng intlayer vào route context. Nó cũng cho phép sử dụng các hàm dịch toàn cục trong ngữ cảnh của request.

Sử dụng

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
  intlayer!.t({
    vi: "Xin chào",
    en: "Hello",
    fr: "Bonjour",
    es: "Hola",
  })
);

Plugin đăng ký context của nó thông qua một derive global, được Elysia định kiểu là Partial<{ intlayer: IntlayerContext }>. Giá trị luôn tồn tại lúc runtime với các route được đăng ký sau .use(intlayer()), vì vậy hãy dùng non-null assertion (intlayer!.t), hoặc optional chaining, để thỏa mãn TypeScript ở chế độ strict.

Các helper tương tự cũng có sẵn dưới dạng các export độc lập, nên bạn có thể gọi chúng mà không cần destructure route context:

import { Elysia } from "elysia";
import { intlayer, t } from "elysia-intlayer";

const app = new Elysia().use(intlayer()).get("/", () =>
  t({
    vi: "Xin chào",
    en: "Hello",
    fr: "Bonjour",
    es: "Hola",
  })
);

Mô tả

Plugin thực hiện các nhiệm vụ sau:

1. Phát hiện locale: Nó đọc locale được client thiết lập một cách tường minh từ storage (cookie, header), sau đó quay về locale được thương lượng từ header Accept-Language.
2. Tiêm vào ngữ cảnh: Nó thêm thuộc tính intlayer vào context route của Elysia (xem bảng Context của route bên dưới).
3. Chuẩn bị dictionary: Nó gọi prepareIntlayer khi plugin được tạo, nhờ vậy dictionary được build khi ứng dụng khởi động.

Context của route

Khi các helper độc lập được gọi bên ngoài một request do plugin xử lý, chúng quay về locale mặc định đã được cấu hình.

Thứ tự phân giải locale

Theo mặc định, plugin phân giải locale theo thứ tự sau:

1. Cookie INTLAYER_LOCALE.
2. Header x-intlayer-locale.
3. Thương lượng qua header Accept-Language.
4. defaultLocale đã được cấu hình.

# Được thương lượng từ `Accept-Language`
curl -H "Accept-Language: fr" http://localhost:3000/
# Bonjour

# Cookie được ưu tiên hơn `Accept-Language`
curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
# Hola

# Header được ưu tiên hơn `Accept-Language`
curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
# Hola

Cấu hình

Plugin đọc tệp intlayer.config.ts của bạn. Bạn có thể tùy chỉnh cookie và header dùng cho việc phát hiện locale:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

Để biết thêm thông tin về cấu hình, hãy truy cập tài liệu cấu hình.

Tài liệu liên quan