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

    Przetłumacz swoją aplikację Analog (Angular) za pomocą Intlayer | Internacjonalizacja (i18n)

    ide.intlayer.org

    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 analogowe

    Intlayer jest zoptymalizowany do doskonałej współpracy z Analogiem, oferując wielojęzyczny routing, obsługę SSR 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 Analog

    Zobacz Szablon aplikacji na GitHubie.

    1. Instalacja zależności

      Zainstaluj niezbędne pakiety za pomocą npm:

      bash
      npm install intlayer angular-intlayer vite-intlayernpx intlayer init

      • intlayer

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

      • angular-intlayer Pakiet integrujący Intlayer z aplikacją Angular. Dostarcza dostawców kontekstu (context providers) i hooki dla internacjonalizacji Angulara.

      • vite-intlayer Pakiet integrujący Intlayer z Vite. Dostarcza wtyczkę (plugin) do obsługi plików deklaracji treści i ustawia aliasy dla optymalnej wydajności.

    2. Konfiguracja 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;
      Za pomocą tego pliku konfiguracyjnego możesz ustawić zlokalizowane adresy URL, przekierowania middleware, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracji.

    3. Zintegruj Intlayer w konfiguracji Vite

      Aby zintegrować Intlayer z Analog, musisz użyć wtyczki vite-intlayer.

      Zmodyfikuj plik vite.config.ts:

      vite.config.ts
      import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import analog from "@analogjs/platform";// https://vitejs.dev/config/export default defineConfig(() => ({  plugins: [    analog(),    intlayer(), // Dodaj wtyczkę Intlayer  ],}));
      Wtyczka intlayer() konfiguruje Vite do pracy z Intlayer. Obsługuje pliki deklaracji treści i ustawia aliasy dla optymalnej wydajności.

    4. Zadeklaruj swoją treść

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

      Deklaracje treści mogą być definiowane w dowolnym miejscu aplikacji, o ile znajdują się 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.

    5. Użyj Intlayer w kodzie

      Aby korzystać z funkcji internacjonalizacji Intlayer w całej aplikacji Analog, musisz dodać Intlayer do konfiguracji aplikacji.

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

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

      src/app/pages/index.page.ts
      import { Component } from "@angular/core";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-home",  standalone: true,  template: `    <div class="content">      <h1>{{ content().title }}</h1>      <p>{{ content().congratulations }}</p>    </div>  `,})export default class HomeComponent {  content = useIntlayer("app");}

      Treść Intlayer jest zwracana jako Signal, więc dostęp do wartości uzyskujesz wywołując sygnał: content().title.

    6. Zmiana języka treści

      Opcjonalne

      Aby zmienić język treści, możesz użyć funkcji setLocale dostarczonej przez funkcję useLocale. Pozwala to ustawić język aplikacji i odpowiednio zaktualizować treść.

      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 na swoich stronach:

      src/app/pages/index.page.ts
      import { Component } from "@angular/core";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "../locale-switcher.component";@Component({  selector: "app-home",  standalone: true,  imports: [LocaleSwitcherComponent],  template: `    <app-locale-switcher></app-locale-switcher>    <div class="content">      <h1>{{ content().title }}</h1>      <p>{{ content().congratulations }}</p>    </div>  `,})export default class HomeComponent {  content = useIntlayer("app");}

    Konfiguracja TypeScript

    Intlayer wykorzystuje rozszerzanie modułów (module augmentation), aby czerpać korzyści z TypeScript i wzmocnić bazę kodu.

    Autouzupełnianie

    Błąd tłumaczenia

    Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy.

    tsconfig.json
    {  // ... Twoje istniejące konfiguracje TypeScript  "include": [    // ... Twoje istniejące konfiguracje TypeScript    ".intlayer/**/*.ts", // Uwzględnij automatycznie generowane typy  ],}

    Konfiguracja Git

    Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich zatwierdzania w repozytorium Git.

    Aby to zrobić, dodaj następujące instrukcje do pliku .gitignore:

    bash
    #  Ignoruj pliki generowane przez Intlayer.intlayer

    Rozszerzenie VS Code

    Aby usprawnić proces programowania 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 inline przetłumaczonej treści.
    • Szybkie akcje ułatwiające tworzenie i aktualizację tłumaczeń.

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

    Dowiedz się więcej

    Aby pójść dalej, możesz zaimplementować edytor wizualny lub wyeksportować treść do zewnętrznego systemu za pomocą CMS.

    Angular 19 (Webpack)
    React CRA