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

express-intlayer to potężne middleware do internacjonalizacji (i18n) dla aplikacji Express, zaprojektowane tak, aby uczynić Twoje usługi backendowe globalnie dostępnymi poprzez dostarczanie spersonalizowanych odpowiedzi w oparciu o preferencje klienta. Ponieważ NestJS jest zbudowany na bazie Express, możesz bezproblemowo zintegrować express-intlayer ze swoimi aplikacjami NestJS, aby skutecznie obsługiwać wielojęzyczne treści.

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ć wyświetlane w komponentach front-end, takich jak toasty czy modale.

• Pobieranie wielojęzycznych treści: 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 sklepy 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 wiadomości w języku odbiorcy może znacząco 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 zwiększyć 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ść przekazu i poprawia ogólne doświadczenie użytkownika.

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

Pierwsze kroki

Utwórz nowy projekt NestJS

npm install -g @nestjs/cli
nest new my-nest-app

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 tsconfig.json

Aby używać Intlayer z TypeScript, upewnij się, że twój plik tsconfig.json jest skonfigurowany do obsługi modułów ES. Możesz to zrobić, ustawiając opcje module oraz moduleResolution na nodenext.

{
  compilerOptions: {
    module: "nodenext",
    moduleResolution: "nodenext",
    // ... inne opcje
  },
}

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],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Zadeklaruj swoją zawartość

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

Twoje deklaracje zawartości mogą być definiowane w dowolnym miejscu w aplikacji, pod warunkiem, że znajdują się 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 middleware Express

Zintegruj middleware express-intlayer ze swoją aplikacją NestJS, aby obsługiwać internacjonalizację:

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { intlayer } from "express-intlayer";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(intlayer()).forRoutes("*"); // Zastosuj do wszystkich tras
  }
}

Używanie tłumaczeń w usługach lub kontrolerach

Możesz teraz użyć funkcji getIntlayer, aby uzyskać dostęp do tłumaczeń w swoich usługach lub kontrolerach:

import { Injectable } from "@nestjs/common";
import { getIntlayer } from "express-intlayer";

@Injectable()
export class AppService {
  getHello(): string {
    return getIntlayer("app").greet; // pobierz tłumaczenie "greet" z przestrzeni "app"
  }
}

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
  middleware: {
    headerName: "my-locale-header", // nazwa nagłówka do wykrywania lokalizacji
    cookieName: "my-locale-cookie", // nazwa ciasteczka do wykrywania lokalizacji
  },
};

export default config;

Domyślnie express-intlayer interpretuje 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 solidne 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 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", // Include the auto-generated types
  ],
}

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 umożliwiające łatwe tworzenie i aktualizowanie tłumaczeń.

Aby uzyskać więcej informacji o korzystaniu z rozszerzenia, zapoznaj się z dokumentacją rozszerzenia Intlayer dla 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