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

Spis treści

Czym jest Intlayer?

Intlayer to innowacyjna biblioteka umiędzynarodowienia (i18n) typu open-source, zaprojektowana w celu uproszczenia obsługi wielojęzyczności w nowoczesnych aplikacjach internetowych.

Z Intlayer możesz:

• Łatwo zarządzać tłumaczeniami za pomocą deklaratywnych słowników na poziomie komponentów.
• Dynamicznie lokalizować metadane, trasy i treści.
• Zapewnić wsparcie TypeScript dzięki automatycznie generowanym typom, poprawiając autouzupełnianie i wykrywanie błędów.
• Korzystać z zaawansowanych funkcji, jak dynamiczne wykrywanie i przełączanie języka.

Przewodnik krok po kroku po konfiguracji Intlayer w aplikacji Angular

Zobacz Szablon aplikacji na GitHubie.

Krok 1: Instalacja zależności

Zainstaluj niezbędne pakiety za pomocą npm:

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

• intlayer

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

• angular-intlayer Pakiet integrujący Intlayer z aplikacją Angular. Dostarcza dostawców kontekstu i hooki dla umiędzynarodowienia Angulara.

• @angular-builders/custom-webpack Wymagany do dostosowania konfiguracji Webpack w Angular CLI.

Krok 2: Konfiguracja projektu

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

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

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

export default config;

Poprzez ten plik konfiguracyjny możesz ustawić zlokalizowane adresy URL, przekierowania middleware, nazwy ciasteczek, lokalizację i rozszerzenia deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracji.

Krok 3: Integracja Intlayer w konfiguracji Angulara

Aby zintegrować Intlayer z Angular CLI, musisz użyć niestandardowego buildera. Ten przewodnik zakłada, że używasz Webpacka (domyślny dla wielu projektów Angular).

Najpierw zmodyfikuj plik angular.json, aby używał niestandardowego buildera Webpack. Zaktualizuj konfiguracje build i serve:

{  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-webpack:browser", // replace "@angular-devkit/build-angular:application",          "options": {            "customWebpackConfig": {              "path": "./webpack.config.ts",              "mergeStrategies": { "module.rules": "prepend" },            },            "main": "src/main.ts", // replace "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-webpack:dev-server",        },      },    },  },}

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

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

import { mergeConfig } from "angular-intlayer/webpack";export default mergeConfig({});

Funkcja mergeConfig konfiguruje Webpacka pod kątem Intlayer. Wstrzykuje IntlayerPlugin (do obsługi plików deklaracji treści) i ustawia aliasy dla optymalnej wydajności.

Krok 4: Deklarowanie treści

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

Twoje deklaracje treści mogą być zdefiniowane w dowolnym miejscu w 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}).

Więcej szczegółów znajdziesz w dokumentacji deklaracji treści.

Krok 5: Wykorzystanie Intlayer w kodzie

Aby korzystać z funkcji umiędzynarodowienia Intlayer w całej aplikacji Angular, musisz dostarczyć Intlayer w konfiguracji 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 dostawcę Intlayer tutaj  ],};

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");}

I w swoim szablonie:

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

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

(Opcjonalnie) Krok 6: Zmiana języka treści

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:

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 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 rozszerzania modułów (module augmentation), aby czerpać korzyści z TypeScript i wzmacniać bazę kodu.

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

{  // ... 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 commitowania do repozytorium Git.

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

#  Ignoruj pliki generowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby poprawić wrażenia z programowania z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer VS Code Extension.

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ąd 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 dla VS Code.

Dowiedz się więcej

Aby pójść dalej, możesz wdrożyć edytor wizualny lub wyeksportować swoje treści za pomocą CMS.