Przetłumacz backend Fastify przy użyciu Intlayer | Internacjonalizacja (i18n)

fastify-intlayer to potężny plugin do internacjonalizacji (i18n) dla aplikacji Fastify, zaprojektowany, aby uczynić twoje usługi backendowe globalnie dostępnymi poprzez dostarczanie zlokalizowanych odpowiedzi na podstawie preferencji klienta.

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 dla dynamicznych komunikatów o błędach, które mogą być pokazywane w komponentach front-endowych, takich jak toasty czy modalne okna.

fastify-intlayer to potężna wtyczka do internacjonalizacji (i18n) dla aplikacji Fastify, zaprojektowana, by uczynić Twoje serwisy backendowe globalnie dostępnymi, dostarczając zlokalizowane odpowiedzi zgodnie z preferencjami klienta.

Praktyczne zastosowania

• Wyświetlanie błędów backendu w języku użytkownika: Gdy wystąpi błąd, wyświetlanie komunikatów w języku ojczystym użytkownika poprawia zrozumienie i zmniejsza frustrację. Jest to szczególnie przydatne w przypadku dynamicznych komunikatów o błędach, które mogą być pokazywane w komponentach front-endowych, takich jak toasty czy modale.
• Pobieranie wielojęzycznych treści: W aplikacjach 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 serwisy e-commerce czy systemy zarządzania treścią (CMS), które muszą wyświetlać opisy produktów, artykuły i inne treści w języku preferowanym przez użytkownika.
• Pobieranie treści wielojęzycznych: Dla 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 serwisy 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 wiadomości e-mail w wielu językach: Niezależnie czy to wiadomości transakcyjne, kampanie marketingowe czy powiadomienia, wysyłanie e-maili w języku odbiorcy może znacząco zwiększyć zaangażowanie i skuteczność.
• Wielojęzyczne powiadomienia push: Dla aplikacji mobilnych wysyłanie powiadomień push w preferowanym języku użytkownika może zwiększyć zaangażowanie i retencję. Ten osobisty akcent sprawia, że powiadomienia wydają się bardziej istotne i skłaniają do działania.
• Inne formy komunikacji: Każda forma komunikacji ze strony backendu, taka jak wiadomości SMS, alerty systemowe czy aktualizacje interfejsu użytkownika, zyskuje na użyciu języka użytkownika, co zapewnia przejrzystość i poprawia ogólne doświadczenie użytkownika.

Dzięki internacjonalizacji backendu Twoja aplikacja nie tylko szanuje różnice kulturowe, ale także lepiej dopasowuje się do potrzeb rynków globalnych, co czyni to kluczowym krokiem w skalowaniu usług na cały świat.

Pierwsze kroki

Instalacja

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

npm install intlayer fastify-intlayernpx intlayer init

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;

Deklarowanie treści

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

import { t, type Dictionary } from "intlayer";const indexContent = {  key: "index",  content: {    exampleOfContent: t({      pl: "Przykład zwracanej treści w języku angielskim",      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 zawartości mogą być zdefiniowane w dowolnym miejscu aplikacji, pod warunkiem że znajdują się w katalogu contentDir (domyślnie ./src) i mają odpowiednie rozszerzenie pliku deklaracji zawartości (domyślnie .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Po więcej szczegółów odnieś się do dokumentacji deklaracji zawartości.

Konfiguracja aplikacji Fastify

Skonfiguruj swoją aplikację Fastify, aby korzystała z 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ę internacjonalizacjiawait fastify.register(intlayer);// Trasyfastify.get("/t_example", async (_req, reply) => {  return t({    pl: "Przykład zwróconej zawartości w języku polskim",    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 serwerconst start = async () => {  try {    await fastify.listen({ port: 3000 });  } catch (err) {    fastify.log.error(err);    process.exit(1);  }};start();

Zgodność

fastify-intlayer jest w pełni zgodny z:

• react-intlayer dla aplikacji React

• next-intlayer dla aplikacji Next.js

• 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 w żądaniach API. Możesz dostosować middleware, aby wykrywać lokalizę przez nagłówki lub ciasteczka:

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 zinterpretuje nagłówek Accept-Language, aby określić preferowany język klienta.

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

Konfiguracja TypeScript

fastify-intlayer wykorzystuje rozbudowane możliwości TypeScript, aby usprawnić proces internacjonalizacji. Statyczne typowanie TypeScript zapewnia, że każdy klucz tłumaczenia jest uwzględniony, zmniejszając ryzyko brakujących tłumaczeń i poprawiając konserwowalność.

Upewnij się, że autogenerowane 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 autogenerowane typy  ],}

Rozszerzenie VS Code

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

Zainstaluj z VS Code Marketplace

To rozszerzenie zapewnia:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podgląd przetłumaczonej zawartości bezpośrednio w edytorze.
• Szybkie akcje umożliwiające łatwe tworzenie i aktualizowanie tłumaczeń.

Aby uzyskać więcej informacji o sposobie korzystania z rozszerzenia, zapoznaj się z dokumentacją Intlayer VS Code Extension.

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