Tłumaczenie backendu Express za pomocą Intlayer | Internacjonalizacja (i18n)

express-intlayer to potężne middleware do internacjonalizacji (i18n) dla aplikacji Express, zaprojektowane, aby uczynić Twoje usługi backendowe globalnie dostępnymi poprzez dostarczanie zlokalizowanych odpowiedzi na podstawie preferencji klienta.

Praktyczne zastosowania

• Wyświetlanie błędów backendu w języku użytkownika: Gdy wystąpi błąd, wyświetlanie komunikatów w ojczystym języku użytkownika poprawia zrozumienie i zmniejsza frustrację. Jest to szczególnie przydatne dla dynamicznych komunikatów o błędach, które mogą być wyświetlane w komponentach front-end, takich jak toasty czy modale.

• Pobieranie treści wielojęzycznych: W przypadku aplikacji pobierających treści z bazy danych, internacjonalizacja zapewnia możliwość serwowania tych treści w wielu językach. Jest to kluczowe dla platform takich jak sklepy internetowe czy systemy zarządzania treścią, które muszą wyświetlać opisy produktów, artykuły i inne treści w preferowanym przez użytkownika języku.

• Wysyłanie wielojęzycznych e-maili: Niezależnie od tego, czy są to e-maile transakcyjne, kampanie marketingowe, czy powiadomienia, wysyłanie wiadomości w języku odbiorcy może znacznie zwiększyć zaangażowanie i skuteczność.

• Wielojęzyczne powiadomienia push: W przypadku aplikacji mobilnych, wysyłanie powiadomień push w preferowanym przez użytkownika języku może poprawić interakcję i retencję. Ten osobisty akcent sprawia, że powiadomienia wydają się bardziej istotne i angażujące.

• Inne formy komunikacji: Każda forma komunikacji z backendu, taka jak wiadomości SMS, alerty systemowe czy aktualizacje interfejsu użytkownika, zyskuje na tym, że jest w języku użytkownika, co zapewnia jasność i poprawia ogólne doświadczenie użytkownika.

Poprzez internacjonalizację backendu, Twoja aplikacja nie tylko szanuje różnice kulturowe, ale także lepiej dostosowuje się do potrzeb globalnego rynku, co stanowi kluczowy krok w skalowaniu usług na całym świecie.

Pierwsze kroki

Zobacz Application Template na GitHub.

Instalacja

Aby rozpocząć korzystanie z express-intlayer, zainstaluj pakiet za pomocą npm:

npx intlayer init --interactive

flaga --interactive jest opcjonalna. Użyj intlayer-cli init, jeśli jesteś agentem AI.

To polecenie wykryje Twoje środowisko i zainstaluje wymagane pakiety. Na przykład:

npm install intlayer express-intlayer

Konfiguracja

Skonfiguruj ustawienia internacjonalizacji, tworząc plik intlayer.config.ts w katalogu głównym projektu:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH_MEXICO,
      Locales.SPANISH_SPAIN,
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Zadeklaruj swoją zawartość

Twórz i zarządzaj deklaracjami zawartości, aby przechowywać tłumaczenia:

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: 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)",
    }),
  },
} satisfies Dictionary;

export default indexContent;

Twoje deklaracje zawartości mogą być definiowane w dowolnym miejscu w Twojej aplikacji, pod warunkiem, że są umieszczone w katalogu contentDir (domyślnie ./src). I mają rozszerzenie pliku deklaracji zawartości (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Aby uzyskać więcej szczegółów, zapoznaj się z dokumentacją deklaracji zawartości.

Konfiguracja aplikacji Express

Skonfiguruj swoją aplikację Express, aby korzystała z express-intlayer:

import express, { type Express } from "express";
import { intlayer, t, getDictionary, getIntlayer } from "express-intlayer";
import dictionaryExample from "./index.content";

const app: Express = express();

// Załaduj handler żądań internacjonalizacji
app.use(intlayer());

// Trasy
app.get("/t_example", (_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)",
    })
  );
});

app.get("/getIntlayer_example", (_req, res) => {
  res.send(getIntlayer("index").exampleOfContent);
});

app.get("/getDictionary_example", (_req, res) => {
  res.send(getDictionary(dictionaryExample).exampleOfContent);
});

// Uruchom serwer
app.listen(3000, () => console.log(`Nasłuchiwanie na porcie 3000`));

Kompatybilność

express-intlayer jest w pełni kompatybilny z:

• react-intlayer dla aplikacji React
• next-intlayer dla aplikacji Next.js
• vite-intlayer dla aplikacji Vite

Działa również bezproblemowo z dowolnym rozwiązaniem do internacjonalizacji w różnych środowiskach, w tym w przeglądarkach i zapytaniach API. Możesz dostosować middleware, aby wykrywać lokalizację za pomocą nagłówków lub ciasteczek:

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

const config: IntlayerConfig = {
  // ... Inne opcje konfiguracji
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

Domyślnie express-intlayer będzie interpretować nagłówek Accept-Language, aby określić preferowany język klienta.

Aby uzyskać więcej informacji na temat konfiguracji i zaawansowanych zagadnień, odwiedź naszą dokumentację.

Konfiguracja TypeScript

express-intlayer wykorzystuje zaawansowane możliwości TypeScript, aby usprawnić proces internacjonalizacji. Statyczne typowanie w TypeScript zapewnia, że każdy klucz tłumaczenia jest uwzględniony, co zmniejsza ryzyko brakujących tłumaczeń i poprawia utrzymanie kodu.

Upewnij się, że automatycznie generowane typy (domyślnie w ./types/intlayer.d.ts) są uwzględnione w Twoim pliku tsconfig.json.

{
  // ... Twoje istniejące konfiguracje TypeScript
  "include": [
    // ... Twoje istniejące konfiguracje TypeScript
    ".intlayer/**/*.ts", // Dołącz automatycznie generowane typy
  ],
}

Rozszerzenie VS Code

Aby poprawić doświadczenie programistyczne z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

Zainstaluj z VS Code Marketplace

To rozszerzenie oferuje:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podglądy w linii przetłumaczonej zawartości.
• Szybkie akcje do łatwego tworzenia i aktualizowania tłumaczeń.

Aby uzyskać więcej informacji na temat korzystania z rozszerzenia, zapoznaj się z dokumentacją rozszerzenia Intlayer VS Code.

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich zatwierdzania do repozytorium Git.

Aby to zrobić, możesz dodać następujące instrukcje do pliku .gitignore:

# Ignoruj pliki generowane przez Intlayer
.intlayer

Często Zadawane Pytania