Tài liệu: Hàm t trong express-intlayer

Hàm t trong gói express-intlayer là tiện ích cốt lõi để cung cấp các phản hồi được địa phương hóa trong ứng dụng Express của bạn. Nó đơn giản hóa việc quốc tế hóa (i18n) bằng cách chọn nội dung một cách động dựa trên ngôn ngữ ưu tiên của người dùng.

Tổng quan

Hàm t được sử dụng để định nghĩa và truy xuất các bản dịch cho một tập hợp ngôn ngữ nhất định. Nó tự động xác định ngôn ngữ phù hợp để trả về dựa trên cài đặt yêu cầu của client, chẳng hạn như header Accept-Language. Nếu ngôn ngữ ưu tiên không có sẵn, nó sẽ tự động chuyển về locale mặc định được chỉ định trong cấu hình của bạn một cách mượt mà.

Các tính năng chính

• Địa phương hóa động: Tự động chọn bản dịch phù hợp nhất cho client.
• Chuyển về locale mặc định: Chuyển về locale mặc định nếu ngôn ngữ ưu tiên của client không có sẵn, đảm bảo trải nghiệm người dùng liên tục.
• Nhẹ và nhanh: Thiết kế cho các ứng dụng hiệu năng cao, đảm bảo chi phí tài nguyên tối thiểu.
• Hỗ trợ Chế độ Nghiêm ngặt: Thực thi tuân thủ nghiêm ngặt các locale đã khai báo để đảm bảo hành vi đáng tin cậy.

Chữ ký Hàm

t(translations: Record<string, string>): string;

Tham số

• translations: Một đối tượng trong đó các khóa là mã locale (ví dụ: en, fr, es-MX) và các giá trị là các chuỗi đã được dịch tương ứng.

Trả về

• Một chuỗi đại diện cho nội dung theo ngôn ngữ ưu tiên của client.

Tải Bộ Xử lý Yêu cầu Quốc tế hóa

Để đảm bảo chức năng quốc tế hóa do express-intlayer cung cấp hoạt động chính xác, bạn phải tải middleware quốc tế hóa ở đầu ứng dụng Express của bạn. Điều này kích hoạt hàm t và đảm bảo xử lý đúng việc phát hiện locale và dịch thuật.

Đặt middleware app.use(intlayer()) trước bất kỳ route nào trong ứng dụng của bạn để đảm bảo tất cả các route đều được hưởng lợi từ tính năng quốc tế hóa:

import express, { type Express } from "express";import { intlayer } from "express-intlayer";const app: Express = express();// Tải bộ xử lý yêu cầu quốc tế hóaapp.use(intlayer());// Định nghĩa các route sau khi đã tải middlewareapp.get("/", (_req, res) => {  res.send(    t({      en: "Hello, World!",      fr: "Bonjour le monde!",      es: "¡Hola, Mundo!",    })  );});

Tại sao điều này là cần thiết

• Phát hiện ngôn ngữ: Middleware intlayer xử lý các yêu cầu đến để phát hiện ngôn ngữ ưu tiên của người dùng dựa trên headers, cookies hoặc các phương pháp cấu hình khác.
• Ngữ cảnh dịch thuật: Thiết lập ngữ cảnh cần thiết để hàm t hoạt động chính xác, đảm bảo các bản dịch được trả về đúng ngôn ngữ.
• Ngăn ngừa lỗi: Nếu không có middleware này, việc sử dụng hàm t sẽ gây ra lỗi thời gian chạy vì thông tin ngôn ngữ cần thiết sẽ không có sẵn.

Ví dụ sử dụng

Ví dụ cơ bản

Phục vụ nội dung được địa phương hóa bằng các ngôn ngữ khác nhau:

app.get("/", (_req, res) => {  res.send(    t({      en: "Welcome!",      fr: "Bienvenue!",      es: "¡Bienvenido!",    })  );});

Yêu cầu từ phía client:

• Một client với Accept-Language: fr sẽ nhận được Bienvenue!.
• Một client với Accept-Language: es sẽ nhận được ¡Bienvenido!.
• Một client với Accept-Language: de sẽ nhận được Welcome! (ngôn ngữ mặc định).

Xử lý lỗi

Cung cấp thông báo lỗi bằng nhiều ngôn ngữ:

app.get("/error", (_req, res) => {  res.status(500).send(    t({      en: "An unexpected error occurred.",      fr: "Une erreur inattendue s'est produite.",      es: "Ocurrió un error inesperado.",    })  );});

Sử dụng các biến thể ngôn ngữ

Chỉ định các bản dịch cho các biến thể ngôn ngữ cụ thể:

app.get("/greet", (_req, res) => {  res.send(    t({      en: "Hello!",      "en-GB": "Hello, mate!",      fr: "Bonjour!",      "es-MX": "¡Hola, amigo!",      "es-ES": "¡Hola!",    })  );});

Các Chủ Đề Nâng Cao

Cơ Chế Dự Phòng (Fallback Mechanism)

Nếu một locale ưu tiên không có sẵn, hàm t sẽ tự động chuyển sang locale mặc định được định nghĩa trong cấu hình:

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

Ví dụ:

• Nếu defaultLocale là Locales.CHINESE và một client yêu cầu Locales.DUTCH, bản dịch trả về sẽ mặc định là giá trị của Locales.CHINESE.
• Nếu defaultLocale không được định nghĩa, hàm t sẽ tự động chuyển sang giá trị của Locales.ENGLISH.

Bắt Buộc Chế Độ Strict

Cấu hình hàm t để bắt buộc tuân thủ nghiêm ngặt các locale đã khai báo:

Ví dụ cấu hình:

import { type IntlayerConfig } from "intlayer";const config = {  // ... Cấu hình hiện có của bạn  internationalization: {    // ... Cấu hình quốc tế hóa hiện có của bạn    strictMode: "strict", // Bắt buộc chế độ nghiêm ngặt  },} satisfies IntlayerConfig;export default config;

Tích hợp TypeScript

Hàm t an toàn về kiểu khi sử dụng với TypeScript. Định nghĩa một đối tượng bản dịch an toàn về kiểu:

import { type LanguageContent } from "express-intlayer";const translations: LanguageContent<string> = {  en: "Good morning!",  fr: "Bonjour!",  es: "¡Buenos días!",};app.get("/morning", (_req, res) => {  res.send(t(translations));});

Các lỗi phổ biến và cách khắc phục

Mẹo sử dụng hiệu quả

1. Tập trung quản lý bản dịch: Sử dụng một module tập trung hoặc các file JSON để quản lý bản dịch nhằm cải thiện khả năng bảo trì.
2. Xác thực bản dịch: Đảm bảo mỗi biến thể ngôn ngữ đều có bản dịch tương ứng để tránh việc fallback không cần thiết.
3. Kết hợp với i18n phía frontend: Đồng bộ hóa với hệ thống quốc tế hóa phía frontend để mang lại trải nghiệm người dùng liền mạch trên toàn ứng dụng.
4. Đánh giá hiệu năng: Kiểm tra thời gian phản hồi của ứng dụng khi thêm bản dịch để đảm bảo ảnh hưởng tối thiểu.

Kết luận

Hàm t là một công cụ mạnh mẽ cho việc quốc tế hóa backend. Bằng cách sử dụng hiệu quả, bạn có thể tạo ra một ứng dụng thân thiện với người dùng và bao quát hơn cho đối tượng toàn cầu. Để biết cách sử dụng nâng cao và các tùy chọn cấu hình chi tiết, hãy tham khảo tài liệu.