Terima notifikasi tentang rilis Intlayer yang akan datang
    Dibuat:2025-04-18Terakhir diperbarui:2025-06-29

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

    Paket ini sedang dalam pengembangan. Lihat issue untuk informasi lebih lanjut. Tunjukkan minat Anda pada Intlayer untuk Angular dengan menyukai issue tersebut

    Apa itu Intlayer?

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

    Dengan Intlayer, Anda dapat:

    • Mengelola terjemahan dengan mudah menggunakan kamus deklaratif di tingkat komponen.
    • Melokalkan metadata, rute, dan konten secara dinamis.
    • Memastikan dukungan TypeScript dengan tipe yang dihasilkan secara otomatis, meningkatkan autocompletion dan deteksi kesalahan.
    • Manfaatkan fitur canggih, seperti deteksi dan pergantian locale secara dinamis.

    Panduan Langkah demi Langkah untuk Mengatur Intlayer dalam Aplikasi Angular

    Langkah 1: Instalasi Dependensi

    Instal paket yang diperlukan menggunakan npm:

    npm install intlayer angular-intlayer @intlayer/webpack
    • intlayer

    • intlayer

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

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

    • @intlayer/webpack

      Paket yang mengintegrasikan Intlayer dengan Webpack. Paket ini digunakan oleh Angular CLI untuk membangun file deklarasi konten dan memantau file tersebut dalam mode pengembangan.

    Langkah 2: Konfigurasi proyek Anda

    Buat file konfigurasi untuk mengatur bahasa-bahasa dalam aplikasi Anda:

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Locale lain 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 lainnya. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.

    Langkah 3: Integrasikan Intlayer dalam Konfigurasi Angular Anda

    Untuk mengintegrasikan Intlayer dengan Angular CLI, Anda memiliki dua opsi tergantung pada builder yang Anda gunakan: esbuild atau webpack.

    Opsi 1: Menggunakan esbuild (Direkomendasikan)

    Pertama, ubah angular.json Anda untuk menggunakan custom esbuild builder. Perbarui konfigurasi build:

    angular.json
    {  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application",          "options": {            "plugins": ["./esbuild/intlayer-plugin.ts"]          }        }      }    }  }}
    Pastikan untuk mengganti your-app-name dengan nama proyek Anda yang sebenarnya di angular.json.

    Selanjutnya, buat file esbuild/intlayer-plugin.ts di root proyek Anda:

    esbuild/intlayer-plugin.ts
    import { prepareIntlayer, watch } from "@intlayer/chokidar";import { getConfiguration, logger } from "@intlayer/config";import type { Plugin } from "esbuild";const intlayer: Plugin = {  name: "intlayer-esbuild-plugin",  setup(build) {    const configuration = getConfiguration();    let isWatching = false;    build.onStart(async () => {      logger("Plugin esbuild Intlayer dimulai", {        level: "info",      });      if (build.initialOptions.watch && !isWatching) {        logger("Mode watch diaktifkan. Memulai watcher...", {          level: "info",        });        watch(configuration);        isWatching = true;      }      try {        await prepareIntlayer(configuration);      } catch (error) {        logger(`Kesalahan pada plugin esbuild Intlayer: ${error}`, {          level: "error",        });      }    });  },};export default intlayer;
    intlayer untuk esbuild memastikan bahwa Intlayer dipersiapkan sebelum proses build dimulai dan memantau perubahan dalam mode pengembangan.

    Opsi 2: Menggunakan Webpack

    Pertama, ubah angular.json Anda untuk menggunakan custom Webpack builder. Perbarui konfigurasi build dan serve:

    angular.json
    {  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-webpack:browser",          "options": {            "customWebpackConfig": {              "path": "./webpack.config.js"            }          }        },        "serve": {          "builder": "@angular-builders/custom-webpack:dev-server"        }      }    }  }}
    Pastikan untuk mengganti your-app-name dengan nama proyek Anda yang sebenarnya di angular.json.

    Selanjutnya, buat file webpack.config.js di root proyek Anda:

    webpack.config.js
    const { IntlayerWebpackPlugin } = require("@intlayer/webpack");module.exports = {  plugins: [new IntlayerWebpackPlugin()],};
    IntlayerWebpackPlugin digunakan untuk mengintegrasikan Intlayer dengan Webpack. Plugin ini memastikan pembuatan file deklarasi konten dan memantau file tersebut dalam mode pengembangan. Plugin ini juga mendefinisikan variabel lingkungan Intlayer di dalam aplikasi. Selain itu, plugin ini menyediakan alias untuk mengoptimalkan performa.

    Langkah 4: Deklarasikan Konten Anda

    Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

    src/app/app.content.ts
    import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    title: t({      en: "Hello",      fr: "Bonjour",      es: "Hola",    }),    congratulations: t({      en: "Congratulations! Your app is running. 🎉",      fr: "Félicitations! Votre application est en cours d'exécution. 🎉",      es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",    }),    exploreDocs: t({      en: "Explore the Docs",      fr: "Explorer les Docs",      es: "Explorar los Docs",    }),    learnWithTutorials: t({      en: "Learn with Tutorials",      fr: "Apprendre avec les Tutoriels",      es: "Aprender con los Tutorios",    }),    cliDocs: "Dokumentasi CLI",    angularLanguageService: t({      en: "Angular Language Service",      fr: "Service de Langage Angular",      es: "Servicio de Lenguaje Angular",    }),    angularDevTools: "Angular DevTools",    github: "Github",    twitter: "Twitter",    youtube: "Youtube",  },} satisfies Dictionary;export default appContent;
    Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama sudah dimasukkan ke dalam direktori contentDir (secara default, ./src). Dan sesuai dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).
    Untuk informasi lebih lanjut, lihat dokumentasi deklarasi konten.

    Langkah 5: Gunakan Intlayer dalam Kode Anda

    Untuk memanfaatkan fitur internasionalisasi Intlayer di seluruh aplikasi Angular Anda, Anda perlu menggunakan fungsi useIntlayer di dalam sebuah komponen. Fungsi ini, yang tersedia dari angular-intlayer, memberikan akses ke terjemahan Anda sebagai sinyal reaktif.

    IntlayerProvider sudah terdaftar di root aplikasi, jadi Anda tidak perlu menambahkannya ke penyedia modul Anda.

    Akses kamus konten Anda di kelas komponen Anda:

    src/app/hello-world.component.ts
    import { Component, signal } from "@angular/core";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-hello-world",  standalone: true,  template: `    <h1>{{ content().title }}</h1>    <div class="card">      <button type="button" (click)="increment()">        {{ content().count }} {{ count() }}      </button>      <p [innerHTML]="content().edit"></p>    </div>    <p class="read-the-docs">{{ content().readTheDocs }}</p>  `,})export class HelloWorldComponent {  content = useIntlayer("helloworld");  count = signal(0);  increment() {    this.count.update((value) => value + 1);  }}

    Konten Intlayer dikembalikan sebagai Signal, jadi Anda mengakses nilai-nilainya dengan memanggil sinyal tersebut di template Anda: 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 locale aplikasi dan memperbarui konten sesuai dengan itu.

    Buat komponen untuk beralih antar bahasa:

    src/app/components/locale-switcher.component.ts
    import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { getLocaleName } from "intlayer";import { useLocale } from "angular-intlayer";import { FormsModule } from "@angular/forms";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule, FormsModule],  template: `    <div class="locale-switcher">      <select [ngModel]="locale()" (ngModelChange)="changeLocale($event)">        <option *ngFor="let loc of availableLocales" [value]="loc">          {{ getLocaleName(loc) }}        </option>      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeInfo = useLocale();  locale = this.localeInfo.locale;  availableLocales = this.localeInfo.availableLocales;  // Mengekspos getLocaleName ke template  getLocaleName = getLocaleName;  changeLocale(newLocale: string) {    this.localeInfo.setLocale(newLocale);  }}

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

    src/app/app.component.ts
    import { Component } from "@angular/core";import { HelloWorldComponent } from "./hello-world.component";import { LocaleSwitcherComponent } from "./components/locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [HelloWorldComponent, LocaleSwitcherComponent],  template: `    <div>      <app-locale-switcher />      <a href="https://vite.dev" target="_blank">        <img src="/vite.svg" class="logo" alt="Logo Vite" />      </a>      <a href="https://angular.dev/" target="_blank">        <img          src="/assets/angular.svg"          class="logo angular"          alt="Logo Angular"        />      </a>    </div>    <app-hello-world />  `,})export class AppComponent {}

    (Opsional) Langkah 7: Tambahkan Routing yang Dilokalkan ke aplikasi Anda

    Menambahkan routing yang dilokalkan dalam aplikasi Angular melibatkan penggunaan Angular Router dengan prefix locale. Ini menciptakan rute unik untuk setiap bahasa, yang berguna untuk SEO.

    Contoh:

    - https://example.com/about- https://example.com/es/about- https://example.com/fr/about

    Pertama, pastikan Anda telah menginstal @angular/router.

    Kemudian, buat konfigurasi router yang menangani routing berbasis locale di app.routes.ts.

    src/app/app.routes.ts
    import { Routes } from "@angular/router";import { configuration, localeFlatMap } from "intlayer";import { HomeComponent } from "./home/home.component";import { RootComponent } from "./root/root.component";const { defaultLocale } = configuration.internationalization;export const routes: Routes = [  localeFlatMap((localizedData) => [    {      path: `${localizedData.urlPrefix}`,      component: RootComponent,      data: { locale: localizedData.locale },    },    {      path: `${localizedData.urlPrefix}/home`,      component: HomeComponent,      data: { locale: localizedData.locale },    },  ]),  { path: "**", redirectTo: `/${defaultLocale}/home` },];

    Kemudian, Anda perlu menyediakan router di app.config.ts Anda.

    src/app/app.config.ts
    import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [provideRouter(routes)],};

    (Opsional) Langkah 8: Ubah URL saat locale berubah

    Untuk secara otomatis memperbarui URL ketika pengguna mengubah bahasa, Anda dapat memodifikasi komponen LocaleSwitcher untuk menggunakan Router Angular:

    src/app/components/locale-switcher.component.ts
    import { Component, inject } from "@angular/core";import { CommonModule } from "@angular/common";import { Router } from "@angular/router";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "angular-intlayer";import { FormsModule } from "@angular/forms";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule, FormsModule],  template: `    <div class="locale-switcher">      <select [ngModel]="locale()" (ngModelChange)="changeLocale($event)">        <option *ngFor="let loc of availableLocales" [value]="loc">          {{ getLocaleName(loc) }}        </option>      </select>    </div>  `,})export class LocaleSwitcherComponent {  private router = inject(Router);  localeInfo = useLocale({    onLocaleChange: (newLocale) => {      const currentPath = this.router.url;      const localizedPath = getLocalizedUrl(currentPath, newLocale);      this.router.navigateByUrl(localizedPath);    },  });  locale = this.localeInfo.locale;  availableLocales = this.localeInfo.availableLocales;  getLocaleName = getLocaleName;  changeLocale(newLocale: string) {    this.localeInfo.setLocale(newLocale);  }}

    (Opsional) Langkah 9: Ganti Atribut Bahasa dan Arah pada Tag HTML

    Ketika aplikasi Anda mendukung beberapa bahasa, sangat penting untuk memperbarui atribut lang dan dir pada tag <html> agar sesuai dengan locale saat ini.

    Anda dapat membuat sebuah service untuk menangani ini secara otomatis.

    src/app/services/i18n-html-attributes.service.ts
    import { Injectable, effect } from "@angular/core";import { useLocale } from "angular-intlayer";import { getHTMLTextDir } from "intlayer";@Injectable({  providedIn: "root",})export class I18nHtmlAttributesService {  private localeInfo = useLocale();  constructor() {    effect(() => {      const newLocale = this.localeInfo.locale();      if (newLocale) {        document.documentElement.lang = newLocale;        document.documentElement.dir = getHTMLTextDir(newLocale);      }    });  }  // Metode ini dapat dipanggil di komponen root aplikasi untuk memastikan layanan diinisialisasi.  init() {}}

    Kemudian, injeksikan dan inisialisasi layanan ini di AppComponent utama Anda:

    src/app/app.component.ts
    import { Component, inject } from "@angular/core";// ... impor lainnyaimport { I18nHtmlAttributesService } from "./services/i18n-html-attributes.service";@Component({  // ...})export class AppComponent {  constructor() {    inject(I18nHtmlAttributesService).init();  }}

    (Opsional) Langkah 10: Membuat Direktif Tautan Terlokalisasi

    Untuk memastikan navigasi aplikasi Anda menghormati locale saat ini, Anda dapat membuat direktif kustom. Direktif ini secara otomatis menambahkan prefix bahasa saat ini pada URL internal.

    src/app/directives/localized-link.directive.ts
    import { Directive, Input, HostBinding, inject } from "@angular/core";import { getLocalizedUrl } from "intlayer";import { useLocale } from "angular-intlayer";@Directive({  selector: "a[appLocalizedLink]",  standalone: true,})export class LocalizedLinkDirective {  @Input("href") originalHref: string = "";  private localeInfo = useLocale();  @HostBinding("href")  get localizedHref(): string {    const locale = this.localeInfo.locale();    const isExternalLink = /^https?:\/\//.test(this.originalHref);    if (isExternalLink || !this.originalHref) {      return this.originalHref;    }    return getLocalizedUrl(this.originalHref, locale);  }}

    Untuk menggunakannya, tambahkan direktif appLocalizedLink ke tag anchor Anda dan pastikan untuk mengimpornya di komponen Anda.

    src/app/app.component.ts
    // ...import { LocalizedLinkDirective } from "./directives/localized-link.directive";@Component({  selector: "app-root",  standalone: true,  imports: [/*...,*/ LocalizedLinkDirective],  template: ` <a href="/home" appLocalizedLink>Beranda</a> `,})export class AppComponent {}

    (Opsional) Langkah 11: Render Markdown

    Intlayer mendukung rendering konten Markdown. Untuk mengonversi Markdown menjadi HTML kaya, Anda dapat mengintegrasikan markdown-it.

    Pertama, instal markdown-it:

    npm install markdown-it# dan tipe-nyanpm install -D @types/markdown-it

    Selanjutnya, konfigurasikan INTLAYER_MARKDOWN_TOKEN di app.config.ts Anda.

    src/app/app.config.ts
    import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { routes } from "./app.routes";import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";import MarkdownIt from "markdown-it";const md = new MarkdownIt({  html: true,  linkify: true,  typographer: true,});export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    createIntlayerMarkdownProvider((markdown) => md.render(markdown)),  ],};

    Secara default, Intlayer akan mengembalikan HTML yang sudah dirender sebagai string. Jika Anda menggunakan [innerHTML] untuk mengikatnya, waspadai implikasi keamanan (XSS). Selalu pastikan konten Anda berasal dari sumber yang terpercaya.

    Untuk skenario yang lebih kompleks, Anda dapat membuat pipe untuk merender HTML dengan aman.

    Konfigurasi TypeScript

    Intlayer menggunakan module augmentation untuk mendapatkan manfaat dari TypeScript dan membuat codebase Anda lebih kuat.

    Autocompletion

    Kesalahan Terjemahan

    Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan secara otomatis.

    tsconfig.json
    {  // ... Konfigurasi TypeScript Anda yang sudah ada  "include": [    // ... Konfigurasi TypeScript Anda yang sudah ada    ".intlayer/**/*.ts", // Sertakan tipe yang dihasilkan otomatis  ],}

    Konfigurasi Git

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

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

    # Abaikan file yang dihasilkan oleh Intlayer.intlayer

    Ekstensi VS Code

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

    Pasang dari VS Code Marketplace

    Ekstensi ini menyediakan:

    • Autocompletion untuk kunci terjemahan.
    • Deteksi kesalahan waktu nyata untuk terjemahan yang hilang.
    • Pratinjau inline dari konten terjemahan.
    • Tindakan cepat untuk dengan mudah membuat dan memperbarui terjemahan.

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


    Melangkah Lebih Jauh

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


    Terima notifikasi tentang rilis Intlayer yang akan datang