Przetłumacz swoją stronę Angular 21 (Vite) za pomocą Intlayer | Umiędzynarodowienie (i18n)

Spis Treści

Czym jest Intlayer?

Intlayer to innowacyjna, darmowa biblioteka umiędzynarodowienia (i18n) zaprojektowana w celu uproszczenia wsparcia wielojęzycznego w nowoczesnych aplikacjach internetowych.

Dzięki Intlayer możesz:

• Łatwo zarządzać tłumaczeniami przy użyciu słowników deklaratywnych na poziomie komponentu.
• Dynamicznie lokalizować metadane, trasy i treść.
• Zapewnić wsparcie TypeScript z autogenerowanymi typami, poprawiającymi autouzupełnianie i wykrywanie błędów.
• Korzystać z zaawansowanych funkcji, takich jak dynamiczne wykrywanie i zmiana języka.

Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji Angular

Zobacz Szablon Aplikacji na GitHubie.

Krok 1: Zainstaluj Zależności

Zainstaluj niezbędne pakiety używając npm:

npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

• intlayer

  Główny pakiet dostarczający narzędzia i18n do zarządzania konfiguracją, tłumaczenia, deklarowania treści, transpilacji oraz poleceń CLI.

• angular-intlayer Pakiet, który integruje Intlayer z aplikacją Angular. Dostarcza on dostawców kontekstu i hooki do umiędzynarodowienia Angular.

• @angular-builders/custom-esbuild Wymagane do dostosowania konfiguracji esbuild w Angular CLI.

Krok 2: Konfiguracja twojego projektu

Utwórz plik konfiguracyjny, aby skonfigurować języki swojej aplikacji:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Twoje inne języki
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Poprzez ten plik konfiguracyjny możesz ustawić zlokalizowane adresy URL, przekierowania oprogramowania pośredniczącego (middleware), nazwy plików cookie, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Aby zapoznać się z pełną listą dostępnych parametrów, zapoznaj się z dokumentacją konfiguracji.

Krok 3: Integracja Intlayer w Konfiguracji Angular

Aby zintegrować Intlayer z Angular CLI, musisz użyć niestandardowego buildera. Niniejszy przewodnik zakłada, że używasz Vite/esbuild (domyślnego w projektach Angular 21).

Najpierw zmodyfikuj plik angular.json, aby użyć niestandardowego buildera esbuild. Zaktualizuj konfiguracje build i serve:

{  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"          "options": {            "define": {              "process.env": "{}",            },            "plugins": ["./esbuild.plugins.ts"],            "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"          "options": {            "prebundle": {              "exclude": [                "intlayer",                "angular-intlayer",                "@intlayer/config/built",                "@intlayer/core"              ]          },        },      },    },  },}

Pamiętaj, aby zastąpić your-app-name rzeczywistą nazwą swojego projektu w pliku angular.json.

Następnie utwórz plik esbuild.plugins.ts w głównym katalogu projektu:

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

Funkcja intlayerEsbuildPlugin konfiguruje esbuild dla narzędzia Intlayer. Wprowadza plugin, aby obsłużyć pliki deklaracji treści oraz ustanawia optymalną konfigurację wydajnościową.

Użytkownicy NX: Buildery Angular w NX ładują pliki wtyczek poprzez natywne rozpoznawanie ESM w Node i nie kompilują plików wtyczek TypeScript w locie. Użyj zamiast tego pliku .mjs i odpowiednio zaktualizuj odniesienie plugins w angular.json:

esbuild.plugins.mjs

Kopiuj zawartość

Kopiuj kod

Skopiuj kod do schowka

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

Następnie w angular.json wskaż "./esbuild.plugins.mjs" zamiast "./esbuild.plugins.ts".

Krok 4: Zadeklaruj swoją Treść

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

Twoje deklaracje treści mogą być zdefiniowane w dowolnym miejscu aplikacji, jeśli są dołączone do katalogu contentDir (domyślnie ./src). Zwróć też uwagę na to, by były zgodne z rozszerzeniami plików z deklaracją treści (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Po więcej szczegółów zapoznaj się z dokumentacją deklaracji treści.

Krok 5: Wykorzystaj Intlayer w Kodzie

Aby korzystać z funkcji umiędzynarodowienia w całej aplikacji Angular, musisz dostarczyć Intlayer w konfiguracji swojej aplikacji.

import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { provideIntlayer } from "angular-intlayer";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    provideIntlayer(), // Dodaj tutaj dostawcę Intlayer  ],};

Następnie możesz użyć funkcji useIntlayer w dowolnym komponencie.

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

A w twoim szablonie:

<div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

Treść z Intlayer jest zwracana jako Signal, więc masz dostęp do jej wartości po wywołaniu sygnału: content().title.

(Opcjonalnie) Krok 6: Zmień język treści

Aby zmienić język treści, możesz użyć funkcji setLocale udostępnianej przez useLocale. Dzięki temu możesz ustawić język aplikacji, a treść zostanie odpowiednio zaktualizowana.

Utwórz komponent do przełączania języków:

import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

Następnie użyj tego komponentu w pliku app.component.ts:

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Konfiguracja TypeScript

Intlayer używa wzbogacania modułów (Module Augmentation), aby zapewnić pełne korzyści z TypeScript i sprawić, by twój kod był bardziej odporny na błędy.

Upewnij się, że twoja konfiguracja TypeScript uwzględnia automatycznie wygenerowane typy.

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

Konfiguracja Git

Zaleca się ignorowanie plików wygenerowanych przez Intlayer. To zapobiega dodaniu ich do twojego repozytorium Git.

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

# Ignoruj pliki wygenerowane przez Intlayer.intlayer

Rozszerzenie do VS Code

Aby poprawić jakość i szybkość pisania kodu z Intlayer, możesz zainstalować oficjalne Rozszerzenie Intlayer VS Code.

Zainstaluj z Marketplace VS Code

Rozszerzenie to zapewnia:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Wbudowane podglądy przetłumaczonych treści.
• Szybkie akcje, by sprawnie stworzyć nowe i zaktualizować istniejące tłumaczenia.

Więcej informacji na temat korzystania z rozszerzenia można znaleźć w Dokumentacji Rozszerzenia Intlayer dla VS Code.

Idź Dalej

By osiągnąć jeszcze więcej, możesz zaimplementować edytor wizualny lub uzewnętrznić swoje treści przy pomocy CMS.