Przetłumacz swój backend Hono używając Intlayer | Internacjonalizacja (i18n)

hono-intlayer to potężne oprogramowanie pośredniczące (middleware) do internacjonalizacji (i18n) dla aplikacji Hono, zaprojektowane w celu udostępnienia usług backendowych globalnie poprzez dostarczanie zlokalizowanych odpowiedzi opartych na preferencjach klienta.

Praktyczne Przypadki Użycia

• Wyświetlanie Błędów Backendowych 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 Wielojęzycznej Treści: W przypadku aplikacji pobierających treść z bazy danych, internacjonalizacja zapewnia możliwość serwowania tej treści w wielu językach. Jest to kluczowe dla platform takich jak witryny 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 Wiadomości E-mail: Niezależnie od tego, czy są to wiadomości 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 skłaniające do działania.

• Inna Komunikacja: 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 internacjonalizację backendu, Twoja aplikacja nie tylko szanuje różnice kulturowe, ale także lepiej dopasowuje się do potrzeb rynku globalnego, co jest kluczowym krokiem w skalowaniu usług na całym świecie.

Pierwsze Kroki

Zobacz Application Template na GitHub.

Instalacja

Aby zacząć korzystać z hono-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 hono-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,
      Locales.POLISH,
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Deklarowanie Treści

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

Deklaracje treści mogą być definiowane w dowolnym miejscu w aplikacji, o ile są zawarte w katalogu contentDir (domyślnie ./src) i pasują 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 Hono

Skonfiguruj aplikację Hono do korzystania z hono-intlayer:

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

const app = new Hono();

// Załaduj obsługę żądań internacjonalizacji
app.use("*", intlayer());

// Trasy
app.get("/t_example", (c) => {
  return c.text(
    t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      pl: "Przykład zwróconej treści w języku polskim",
    })
  );
});

app.get("/getIntlayer_example", (c) => {
  return c.json(getIntlayer("index").exampleOfContent);
});

app.get("/getDictionary_example", (c) => {
  return c.json(getDictionary(dictionaryExample).exampleOfContent);
});

export default app;

Kompatybilność

hono-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 żądaniach API. Możesz dostosować middleware, aby wykrywał język poprzez nagłówki lub pliki cookie:

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 hono-intlayer będzie interpretować nagłówek Accept-Language w celu określenia preferowanego języka klienta.

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

Konfiguracja TypeScript

hono-intlayer wykorzystuje potężne możliwości TypeScript, aby usprawnić proces internacjonalizacji. Statyczne typowanie TypeScript zapewnia uwzględnienie każdego klucza tłumaczenia, zmniejszając ryzyko brakujących tłumaczeń i poprawiając łatwość utrzymania.

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 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ądy inline przetłumaczonej treści.
• Szybkie akcje ułatwiające tworzenie i aktualizowanie tłumaczeń.

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

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć zatwierdzania ich 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