Creation:2025-04-18Last update:2026-05-31

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

    Spis Treści

    Dlaczego Interlayer zamiast alternatyw?

    W porównaniu do głównych rozwiązań, takich jak ngx-translate czy angular-l10n, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:

    Pełne pokrycie kątowe

    Intlayer jest zoptymalizowany do doskonałej współpracy z Angularem, oferując zakres zawartości na poziomie komponentu, tłumaczenia z opóźnieniem i wszystkie funkcje potrzebne do skalowania internacjonalizacji (i18n).

    Rozmiar bundle'a

    Zamiast ładować ogromne pliki JSON na swoje strony, ładuj tylko niezbędną treść. Intlayer pomaga zmniejszyć rozmiary bundle'a i stron nawet o 50%.

    Łatwość konserwacji

    Określanie zakresu zawartości aplikacji ułatwia konserwację aplikacji na dużą skalę. Możesz powielić lub usunąć pojedynczy folder funkcji bez obciążania psychicznego koniecznością przeglądania całej bazy kodu zawartości. Dodatkowo Inlayer jest w pełni napisany, aby zapewnić dokładność treści.

    Agent AI

    Wspólna lokalizacja treści zmniejsza potrzebny kontekst dzięki modelom dużego języka (LLM). Intlayer zawiera także zestaw narzędzi, taki jak CLI do sprawdzania brakujących tłumaczeńLSP, MCP i umiejętności agenta, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.

    Automatyzacja

    Korzystaj z automatyzacji, aby tłumaczyć w swoim potoku CI/CD przy użyciu wybranego LLM na koszt dostawcy sztucznej inteligencji. Intlayer oferuje także kompilator do automatyzacji ekstrakcji treści, a także [platformę internetową] (/pl/doc/concept/cms), która pomaga tłumaczyć w tle.

    Wydajność

    Łączenie ogromnych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Inlayer optymalizuje ładowanie treści w czasie kompilacji.

    Skalowanie bez użycia dewelopera

    Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia samodzielny edytor wizualny i pełny CMS, który pomoże Ci zarządzać wielojęzyczną treścią w w czasie rzeczywistym, dzięki czemu współpraca z tłumaczami, copywriterami i innymi członkami zespołu będzie płynna. Treść może być przechowywana lokalnie i/lub zdalnie.

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

    ide.intlayer.org

    Zobacz Szablon Aplikacji na GitHubie.

    1. Zainstaluj Zależności

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

      bash
      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.

    2. Konfiguracja twojego projektu

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

      intlayer.config.ts
      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.

    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:

      angular.json
      {  "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:

      esbuild.plugins.ts
      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
      import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

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

    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,md,mdx,yaml,yml}).
      Po więcej szczegółów zapoznaj się z dokumentacją deklaracji treści.

    5. Wykorzystaj Intlayer w Kodzie

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

      src/app/app.config.ts
      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.

      src/app/app.component.ts
      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:

      src/app/app.component.html
      <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.

    6. Zmień język treści

      Opcjonalne

      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:

      src/app/locale-switcher.component.ts
      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:

      src/app/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.

    Autouzupełnianie

    Błąd tłumaczenia

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

    tsconfig.json
    {  // ... 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:

    bash
    # 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.

    Vite dan Lit
    Angular 19 (Webpack)