Przetłumacz swoją stronę backendową Fastify za pomocą Intlayer | Umiędzynarodowienie (i18n)

fastify-intlayer to potężna wtyczka do umiędzynarodowienia (i18n) dla aplikacji Fastify, zaprojektowana, aby uczynić Twoje usługi backendowe dostępnymi globalnie poprzez dostarczanie zlokalizowanych odpowiedzi na podstawie preferencji klienta.

Zobacz implementację pakietu na GitHub: https://github.com/aymericzip/intlayer/tree/main/packages/fastify-intlayer

Praktyczne przypadki użycia

• 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 w przypadku dynamicznych komunikatów o błędach, które mogą być wyświetlane w komponentach front-endowych, takich jak toasty czy modale.
• Pobieranie treści wielojęzycznych: W przypadku aplikacji pobierających treści z bazy danych, umiędzynarodowienie zapewnia, że można serwować te treści w wielu językach. Jest to kluczowe dla platform takich jak strony e-commerce czy systemy zarządzania treścią, które muszą wyświetlać opisy produktów, artykuły i inne treści w języku preferowanym przez użytkownika.
• Wysyłanie wielojęzycznych e-maili: Niezależnie od tego, czy są to e-maile transakcyjne, kampanie marketingowe czy powiadomienia, wysyłanie e-maili 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 języku użytkownika może poprawić interakcję i retencję. Ten osobisty akcent sprawia, że powiadomienia wydają się bardziej istotne i zachęcają do działania.
• Inne formy komunikacji: Każda forma komunikacji z backendu, taka jak wiadomości SMS, alerty systemowe czy aktualizacje interfejsu użytkownika, zyskuje na byciu w języku użytkownika, zapewniając jasność i poprawiając ogólne wrażenia użytkownika.

Poprzez umiędzynarodowienie backendu, Twoja aplikacja nie tylko szanuje różnice kulturowe, ale także lepiej dopasowuje się do potrzeb globalnego rynku, co jest kluczowym krokiem w skalowaniu usług na całym świecie.

Pierwsze kroki

Zobacz szablon aplikacji na GitHub.

Instalacja

Aby zacząć korzystać z fastify-intlayer, zainstaluj pakiet za pomocą npm:

npm install intlayer fastify-intlayernpx intlayer init

Konfiguracja

Skonfiguruj ustawienia umiędzynarodowienia, tworząc plik intlayer.config.ts w głównym katalogu 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;

Deklarowanie treści

Twórz i zarządzaj swoimi deklaracjami treś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;

Deklaracje treści mogą być definiowane w dowolnym miejscu aplikacji, o ile znajdują się w katalogu contentDir (domyślnie ./src). Muszą również pasować do rozszerzenia pliku deklaracji treści (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Więcej szczegółów znajdziesz w dokumentacji deklaracji treści.

Konfiguracja aplikacji Fastify

Skonfiguruj swoją aplikację Fastify tak, aby używała fastify-intlayer:

import Fastify from "fastify";
import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";
import dictionaryExample from "./index.content";

const fastify = Fastify({ logger: true });

// Załaduj wtyczkę umiędzynarodowienia
await fastify.register(intlayer);

// Trasy
fastify.get("/t_example", async (_req, reply) => {
  return 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)",
  });
});

fastify.get("/getIntlayer_example", async (_req, reply) => {
  return getIntlayer("index").exampleOfContent;
});

fastify.get("/getDictionary_example", async (_req, reply) => {
  return getDictionary(dictionaryExample).exampleOfContent;
});

// Uruchom serwer
const start = async () => {
  try {
    await fastify.listen({ port: 3000 });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

Kompatybilność

fastify-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 umiędzynarodowienia w różnych środowiskach, w tym w przeglądarkach i zapytaniach API. Możesz dostosować oprogramowanie pośredniczące (middleware), aby wykrywało lokalizację za pomocą nagłówków lub plików cookie:

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

const config: IntlayerConfig = {
  // ... Inne opcje konfiguracji
  middleware: {
    headerName: "my-locale-header",
    cookieName: "my-locale-cookie",
  },
};

export default config;

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

Więcej informacji na temat konfiguracji i zaawansowanych zagadnień znajdziesz w naszej dokumentacji.

Konfiguracja TypeScript

fastify-intlayer wykorzystuje potężne możliwości TypeScript, aby usprawnić proces umiędzynarodowienia. Statyczne typowanie TypeScript zapewnia, że każdy klucz tłumaczenia jest uwzględniony, co zmniejsza ryzyko brakujących tłumaczeń i poprawia łatwość konserwacji.

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

{  // ... Twoje istniejące konfiguracje TypeScript  "include": [    // ... Twoje istniejące konfiguracje TypeScript    ".intlayer/**/*.ts", // Uwzględnij automatycznie wygenerowane typy  ],}

Rozszerzenie VS Code

Aby poprawić wrażenia z programowania z Intlayer, możesz zainstalować oficjalne Rozszerzenie Intlayer dla VS Code.

Zainstaluj z VS Code Marketplace

To rozszerzenie zapewnia:

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

Więcej szczegółów na temat korzystania z rozszerzenia znajdziesz w dokumentacji rozszerzenia Intlayer dla VS Code.

Konfiguracja Git

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

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

# Ignoruj pliki generowane przez Intlayer.intlayer