Dokumentacja: funkcja t w express-intlayer

Funkcja t w pakiecie express-intlayer jest podstawowym narzędziem do dostarczania zlokalizowanych odpowiedzi w Twojej aplikacji Express. Upraszcza internacjonalizację (i18n) poprzez dynamiczny wybór treści na podstawie preferowanego języka użytkownika.

Przegląd

Funkcja t służy do definiowania i pobierania tłumaczeń dla określonego zestawu języków. Automatycznie ustala odpowiedni język do zwrócenia na podstawie ustawień żądania klienta, takich jak nagłówek Accept-Language. Jeśli preferowany język nie jest dostępny, funkcja płynnie przełącza się na domyślną lokalizację określoną w Twojej konfiguracji.

Kluczowe cechy

• Dynamiczna lokalizacja: Automatycznie wybiera najbardziej odpowiednie tłumaczenie dla klienta.
• Powrót do domyślnej lokalizacji: W przypadku braku preferowanego języka klienta, następuje powrót do domyślnej lokalizacji, zapewniając ciągłość doświadczenia użytkownika.
• Lekka i szybka: Zaprojektowana z myślą o aplikacjach o wysokiej wydajności, zapewniając minimalne obciążenie.
• Obsługa trybu ścisłego: Wymuszanie ścisłego przestrzegania zadeklarowanych lokalizacji dla niezawodnego działania.

Sygnatura funkcji

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

Parametry

• translations: Obiekt, w którym kluczami są kody lokalizacji (np. en, fr, es-MX), a wartościami odpowiadające im przetłumaczone ciągi znaków.

Zwraca

• Ciąg znaków reprezentujący zawartość w preferowanym języku klienta.

Ładowanie obsługi żądań internacjonalizacji

Aby zapewnić poprawne działanie funkcjonalności internacjonalizacji dostarczanej przez express-intlayer, musisz załadować middleware internacjonalizacji na początku swojej aplikacji Express. To umożliwia funkcji t oraz zapewnia prawidłowe wykrywanie lokalizacji i tłumaczenie.

Umieść middleware app.use(intlayer()) przed jakimikolwiek trasami w swojej aplikacji, aby zapewnić, że wszystkie trasy korzystają z internacjonalizacji:

import express, { type Express } from "express";import { intlayer } from "express-intlayer";const app: Express = express();// Załaduj obsługę żądań internacjonalizacjiapp.use(intlayer());// Zdefiniuj swoje trasy po załadowaniu middlewareapp.get("/", (_req, res) => {  res.send(    t({      en: "Hello, World!",      fr: "Bonjour le monde!",      es: "¡Hola, Mundo!",    })  );});

Dlaczego to jest wymagane

• Wykrywanie lokalizacji: Middleware intlayer przetwarza przychodzące żądania, aby wykryć preferowaną lokalizację użytkownika na podstawie nagłówków, ciasteczek lub innych skonfigurowanych metod.
• Kontekst tłumaczenia: Ustawia niezbędny kontekst dla funkcji t, aby działała poprawnie, zapewniając zwracanie tłumaczeń w odpowiednim języku.
• Zapobieganie błędom: Bez tego middleware użycie funkcji t spowoduje błędy w czasie wykonywania, ponieważ nie będzie dostępna niezbędna informacja o lokalizacji.

Przykłady użycia

Podstawowy przykład

Serwowanie zlokalizowanej zawartości w różnych językach:

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

Żądania klientów:

• Klient z nagłówkiem Accept-Language: fr otrzyma Bienvenue!.
• Klient z nagłówkiem Accept-Language: es otrzyma ¡Bienvenido!.
• Klient z nagłówkiem Accept-Language: de otrzyma Welcome! (domyślna lokalizacja).

Obsługa błędów

Dostarczanie komunikatów o błędach w wielu językach:

javascript fileName="src/index.ts" codeFormat="typescript"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.",    })  );});

Używanie wariantów lokalizacyjnych

Określ tłumaczenia dla wariantów specyficznych dla lokalizacji:

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

Zaawansowane tematy

Mechanizm zapasowy (Fallback)

Jeśli preferowana lokalizacja nie jest dostępna, funkcja t automatycznie użyje lokalizacji domyślnej zdefiniowanej w konfiguracji:

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

Na przykład:

• Jeśli defaultLocale to Locales.CHINESE, a klient zażąda Locales.DUTCH, zwrócone tłumaczenie będzie domyślnie wartością Locales.CHINESE.
• Jeśli defaultLocale nie jest zdefiniowane, funkcja t automatycznie użyje wartości Locales.ENGLISH.

Wymuszanie trybu ścisłego

Skonfiguruj funkcję t, aby wymusić ścisłe przestrzeganie zadeklarowanych lokalizacji:

Przykład konfiguracji:

import { type IntlayerConfig } from "intlayer";const config = {  // ... Twoja istniejąca konfiguracja  internationalization: {    // ... Twoja istniejąca konfiguracja internacjonalizacji    strictMode: "strict", // Wymuś tryb ścisły  },} satisfies IntlayerConfig;export default config;

Integracja z TypeScript

Funkcja t jest bezpieczna typowo, gdy używana jest z TypeScript. Zdefiniuj typowo bezpieczny obiekt tłumaczeń:

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));});

Typowe błędy i rozwiązywanie problemów

Wskazówki dotyczące efektywnego użycia

1. Centralizuj tłumaczenia: Używaj scentralizowanego modułu lub plików JSON do zarządzania tłumaczeniami, aby poprawić łatwość utrzymania.
2. Weryfikuj tłumaczenia: Upewnij się, że każda wersja językowa ma odpowiadające tłumaczenie, aby uniknąć niepotrzebnego cofania się do domyślnego języka.
3. Łącz z i18n frontendowym: Synchronizuj z międzynarodowymi ustawieniami frontendu, aby zapewnić spójne doświadczenie użytkownika w całej aplikacji.
4. Testuj wydajność: Sprawdzaj czasy odpowiedzi aplikacji po dodaniu tłumaczeń, aby zapewnić minimalny wpływ na wydajność.

Podsumowanie

Funkcja t jest potężnym narzędziem do internacjonalizacji backendu. Dzięki jej efektywnemu wykorzystaniu możesz stworzyć bardziej inkluzywną i przyjazną dla użytkownika aplikację dla globalnej publiczności. Dla zaawansowanego użycia i szczegółowych opcji konfiguracji, zapoznaj się z dokumentacją.