Terjemahkan situs web Angular 21 (Vite) Anda menggunakan Intlayer | Internasionalisasi (i18n)

Daftar Isi

Apa itu Intlayer?

Intlayer adalah pustaka internasionalisasi (i18n) inovatif dan sumber terbuka yang dirancang untuk menyederhanakan dukungan multibahasa dalam aplikasi web modern.

Dengan Intlayer, Anda dapat:

• Mengelola terjemahan dengan mudah menggunakan kamus deklaratif pada tingkat komponen.
• Melokalkan metadata secara dinamis, rute, dan konten.
• Memastikan dukungan TypeScript dengan tipe yang dibuat secara otomatis, meningkatkan autocompletion dan deteksi kesalahan.
• Mendapatkan manfaat dari fitur lanjutan, seperti deteksi lokal dan perpindahan dinamis.

Panduan Langkah demi Langkah untuk Mengatur Intlayer di Aplikasi Angular

Lihat Templat Aplikasi di GitHub.

Langkah 1: Instal Dependensi

Instal paket yang diperlukan menggunakan npm:

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

• intlayer

  Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, deklarasi konten, kompilasi silang, dan perintah CLI.

• angular-intlayer Paket yang mengintegrasikan Intlayer dengan aplikasi Angular. Ini menyediakan context providers dan hooks untuk internasionalisasi Angular.

• @angular-builders/custom-esbuild Diperlukan untuk menyesuaikan konfigurasi esbuild dari Angular CLI.

Langkah 2: Konfigurasi proyek Anda

Buat file konfigurasi untuk mengonfigurasi bahasa aplikasi Anda:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Bahasa lainnya milik Anda
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Melalui file konfigurasi ini, Anda dapat mengatur URL yang dilokalkan, pengalihan middleware, nama cookie, lokasi dan ekstensi deklarasi konten Anda, menonaktifkan log Intlayer di konsol, dan banyak lagi. Untuk daftar lengkap parameter yang tersedia, rujuk ke dokumentasi konfigurasi.

Langkah 3: Integrasikan Intlayer dalam Konfigurasi Angular Anda

Untuk mengintegrasikan Intlayer dengan Angular CLI, Anda perlu menggunakan pembuat (builder) kustom. Panduan ini mengasumsikan Anda menggunakan Vite/esbuild (default untuk proyek Angular 21).

Pertama, modifikasi angular.json Anda untuk menggunakan pembuat esbuild kustom. Perbarui konfigurasi build dan 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"              ]          },        },      },    },  },}

Pastikan untuk mengganti your-app-name dengan nama aktual proyek Anda di angular.json.

Selanjutnya, buat file esbuild.plugins.ts di root proyek Anda:

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

Fungsi intlayerEsbuildPlugin mengonfigurasi esbuild dengan Intlayer. Ini memasukkan plugin untuk menangani file deklarasi konten dan mengatur konfigurasi untuk kinerja optimal.

Pengguna NX: Pembangun Angular NX memuat file plugin melalui resolusi ESM asli Node dan tidak mengkompilasi file plugin TypeScript secara langsung. Gunakan file .mjs sebagai gantinya dan perbarui referensi plugins di angular.json yang sesuai:

esbuild.plugins.mjs

Salin konten

Salin kode

Salin kode ke clipboard

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

Kemudian di angular.json arahkan ke "./esbuild.plugins.mjs" alih-alih "./esbuild.plugins.ts".

Langkah 4: Deklarasikan Konten Anda

Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

Deklarasi konten Anda dapat ditentukan di mana saja di aplikasi Anda selama mereka disertakan dalam direktori contentDir (secara default, ./src). Dan cocok dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Untuk detail lebih lanjut, rujuk ke dokumentasi deklarasi konten.

Langkah 5: Manfaatkan Intlayer dalam Kode Anda

Untuk memanfaatkan fitur internasionalisasi Intlayer di seluruh aplikasi Angular Anda, Anda perlu menyediakan Intlayer di konfigurasi aplikasi Anda.

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(), // Tambahkan penyedia Intlayer di sini  ],};

Kemudian, Anda dapat menggunakan fungsi useIntlayer dalam komponen mana pun.

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

Dan di template Anda:

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

Konten Intlayer dikembalikan sebagai Signal, jadi Anda mengakses nilai-nilainya dengan memanggil sinyal: content().title.

(Opsional) Langkah 6: Ubah bahasa konten Anda

Untuk mengubah bahasa konten Anda, Anda dapat menggunakan fungsi setLocale yang disediakan oleh fungsi useLocale. Ini memungkinkan Anda untuk mengatur lokal aplikasi dan memperbarui konten sesuai dengan hal itu.

Buat komponen untuk beralih antara bahasa:

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

Kemudian, gunakan komponen ini di app.component.ts Anda:

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

Konfigurasi TypeScript

Intlayer menggunakan Augmentasi Modul (Module Augmentation) untuk mendapatkan manfaat dari TypeScript dan membuat basis kode Anda lebih kuat.

Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dibuat secara otomatis.

{  // ... Konfigurasi TypeScript Anda yang sudah ada  "include": [    // ... Konfigurasi TypeScript Anda yang sudah ada    ".intlayer/**/*.ts", // Menyertakan tipe yang dibuat secara otomatis  ],}

Konfigurasi Git

Disarankan untuk mengabaikan file yang dihasilkan oleh Intlayer. Ini memungkinkan Anda untuk menghindari komit file tersebut ke repositori Git Anda.

Untuk melakukannya, Anda dapat menambahkan instruksi berikut ke file .gitignore Anda:

# Mengabaikan file yang dihasilkan oleh Intlayer.intlayer

Ekstensi VS Code

Untuk meningkatkan pengalaman pengembangan Anda dengan Intlayer, Anda dapat menginstal Ekstensi Intlayer VS Code resmi.

Instal dari VS Code Marketplace

Ekstensi ini menyediakan:

• Autocompletion untuk kunci terjemahan.
• Deteksi kesalahan secara real-time untuk terjemahan yang hilang.
• Pratinjau sebaris untuk konten yang diterjemahkan.
• Tindakan cepat untuk membuat dan memperbarui terjemahan dengan mudah.

Untuk detail lebih lanjut tentang cara menggunakan ekstensi ini, rujuk ke dokumentasi Ekstensi VS Code Intlayer.

Melangkah Lebih Jauh

Untuk melangkah lebih jauh, Anda dapat mengimplementasikan editor visual atau mengeksternalisasi konten Anda menggunakan CMS.