Creation:2026-03-23Last update:2026-05-31

    Terjemahkan situs web Vite dan Lit Anda dengan Intlayer | Internasionalisasi (i18n)

    ide.intlayer.org

    Daftar Isi

    Mengapa Intlayer dibandingkan alternatif?

    Dibandingkan dengan solusi utama seperti lit-localize atau i18next, Intlayer adalah solusi yang hadir dengan pengoptimalan terintegrasi seperti:

    Intlayer dioptimalkan agar berfungsi sempurna dengan Lit dengan menawarkan pelingkupan konten tingkat Komponen Web, dukungan TypeScript, dan semua fitur yang diperlukan untuk penskalaan internasionalisasi (i18n).

    Daripada memuat file JSON berukuran besar ke halaman Anda, muat saja konten yang diperlukan. Intlayer membantu mengurangi ukuran bundle dan halaman Anda hingga 50%.

    Mencakup konten aplikasi Anda memfasilitasi pemeliharaan untuk aplikasi berskala besar. Anda dapat menduplikasi atau menghapus satu folder fitur tanpa beban mental untuk meninjau seluruh basis kode konten Anda. Selain itu, Intlayer diketik sepenuhnya untuk memastikan keakuratan konten Anda.

    Menempatkan konten bersama mengurangi konteks yang diperlukan dengan Model Bahasa Besar (LLM). Intlayer juga dilengkapi dengan serangkaian alat, seperti CLI untuk menguji terjemahan yang hilang,LSP, MCP, dan agent skill, untuk menjadikan pengalaman pengembang (DX) lebih lancar bagi agen AI.

    Gunakan otomatisasi untuk menerjemahkan dalam saluran CI/CD Anda menggunakan LLM pilihan Anda dengan biaya penyedia AI Anda. Intlayer juga menawarkan compiler untuk mengotomatiskan ekstraksi konten, serta platform web untuk membantu menerjemahkan di latar belakang.

    Menghubungkan file JSON berukuran besar ke komponen dapat menyebabkan masalah kinerja dan reaktivitas. Intlayer mengoptimalkan pemuatan konten Anda pada waktu pembuatan.

    Lebih dari sekedar solusi i18n, Intlayer menyediakan editor visual yang dihosting sendiri dan CMS lengkap untuk membantu Anda mengelola konten multibahasa secara real-time, membuat kolaborasi dengan penerjemah, copywriter, dan anggota tim lainnya menjadi lancar. Konten dapat disimpan secara lokal dan/atau jarak jauh.

    Panduan langkah demi langkah untuk menyiapkan Intlayer di aplikasi Vite dan Lit

    1. Instal Dependensi

      Instal paket-paket yang diperlukan menggunakan npm:

      bash
      npm install intlayer lit-intlayernpm install vite-intlayer --save-devnpx intlayer init

      • intlayer

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

      • lit-intlayer Paket yang mengintegrasikan Intlayer dengan aplikasi Lit. Paket ini menyediakan hook berbasis ReactiveController (useIntlayer, useLocale, dll.) sehingga LitElement secara otomatis merender ulang saat bahasa berubah.

      • vite-intlayer Menyertakan plugin Vite untuk mengintegrasikan Intlayer dengan Vite bundler, serta middleware untuk mendeteksi bahasa pilihan pengguna, mengelola cookie, dan menangani pengalihan URL.

    2. Konfigurasi Proyek Anda

      Buat file konfigurasi untuk menyiapkan bahasa aplikasi Anda:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Bahasa lainnya
    ],
    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, lihat dokumentasi konfigurasi.

    3. Integrasikan Intlayer ke dalam Konfigurasi Vite Anda

      Tambahkan plugin intlayer ke konfigurasi Anda.

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});
      Plugin Vite intlayer() digunakan untuk mengintegrasikan Intlayer dengan Vite. Plugin ini memastikan pembangunan file deklarasi konten dan memantaunya dalam mode pengembangan. Plugin ini mendefinisikan variabel lingkungan Intlayer di dalam aplikasi Vite. Selain itu, plugin ini menyediakan alias untuk mengoptimalkan performa.

    4. Bootstrap Intlayer di Entry Point Anda

      Panggil installIntlayer() sebelum elemen kustom apa pun didaftarkan sehingga singleton lokal global siap saat elemen pertama terhubung.

      src/main.ts
      import { installIntlayer } from "lit-intlayer";// Harus dipanggil sebelum LitElement apa pun terhubung ke DOM.installIntlayer();// Impor dan daftarkan elemen kustom Anda.import "./my-element.js";

      Jika Anda juga menggunakan deklarasi konten md() (Markdown), instal juga perender markdown:

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

    5. Deklarasikan Konten Anda

      Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

      src/app.content.ts
      import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Lit",

    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    litLogo: t({
      en: "Lit logo",
      fr: "Logo Lit",
      es: "Logo Lit",
    }),

    count: t({
      en: "count is {{count}}",
      fr: "le compte est {{count}}",
      es: "el recuento es {{count}}",
    }),

    readTheDocs: t({
      en: "Click on the Vite and Lit logos to learn more",
      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Lit para obtener lebih lanjut",
    }),
  },
} satisfies Dictionary;

export default appContent;

      Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama disertakan dalam direktori contentDir (secara default, ./src) dan sesuai dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

      Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

    6. Gunakan Intlayer di LitElement Anda

      Gunakan useIntlayer di dalam LitElement. Ini mengembalikan proxy ReactiveController yang secara otomatis memicu perenderan ulang setiap kali bahasa aktif berubah - tidak diperlukan pengaturan tambahan.

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  @property({ type: Number })  count = 0;  // useIntlayer mendaftarkan dirinya sebagai ReactiveController.  // Elemen dirrender ulang secara otomatis saat bahasa berubah.  private content = useIntlayer(this, "app");  override render() {    const { content } = this;    return html`      <h1>${content.title}</h1>      <img src="/vite.svg" alt=${content.viteLogo.value} />      <img src="/lit.svg" alt=${content.litLogo.value} />      <button @click=${() => this.count++}>        ${content.count({ count: this.count })}      </button>      <p>${content.readTheDocs}</p>    `;  }}

      Saat Anda memerlukan string terjemahan dalam atribut HTML asli (misalnya, alt, aria-label, title), hubungi .value pada simpul daun:

      typescript
      html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;

    7. Ubah Bahasa Konten Anda

      Opsional

      Untuk mengubah bahasa konten Anda, gunakan metode setLocale yang disediakan oleh pengontrol useLocale.

      src/locale-switcher.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

    8. Render Konten Markdown dan HTML

      Opsional

      Intlayer mendukung deklarasi konten md() dan html(). Di Lit, output terkompilasi disuntikkan sebagai HTML mentah melalui arahan unsafeHTML.

      Render HTML terkompilasi di elemen Anda:

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement {  private content = useIntlayer(this, "app");  override render() {    return html`      <div class="edit-note">        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}      </div>    `;  }}
      TIP
      String(content.editNote) memanggil toString() pada IntlayerNode, yang mengembalikan string Markdown mentah. Berikan ke compileMarkdown untuk mendapatkan string HTML, lalu render dengan arahan unsafeHTML Lit.

    9. Tambahkan Perutean Terlokalisasi ke Aplikasi Anda

      Opsional

      Untuk membuat rute unik untuk setiap bahasa (berguna untuk SEO), Anda dapat menggunakan perute sisi klien bersama dengan pembantu localeMap / localeFlatMap Intlayer, dan plugin Vite intlayerProxy untuk deteksi bahasa sisi server.

      Pertama, tambahkan intlayerProxy ke konfigurasi Vite Anda:

      Perhatikan bahwa untuk menggunakan intlayerProxy dalam produksi, Anda perlu memindahkan vite-intlayer dari devDependencies ke dependencies.
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer(), intlayerProxy()],
});

    10. Ubah URL saat Bahasa Berubah

      Opsional

      Untuk memperbarui URL browser saat bahasa berubah, gunakan useRewriteURL beserta pengalih bahasa:

      src/locale-switcher.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  // Menulis ulang URL saat ini secara otomatis saat bahasa berubah.  private _rewriteURL = useRewriteURL(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

    11. Alihkan Atribut Bahasa dan Arah HTML

      Opsional

      Perbarui atribut lang dan dir dari tag <html> agar sesuai dengan bahasa saat ini untuk aksesibilitas dan SEO.

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  private locale = useLocale(this, {    onLocaleChange: (loc) => {      document.documentElement.lang = loc;      document.documentElement.dir = getHTMLTextDir(loc);    },  });  override render() {    return html`<!-- konten Anda -->`;  }}

    12. Ekstrak Konten Komponen Anda

      Opsional

      Jika Anda memiliki codebase yang ada, mengubah ribuan file bisa memakan waktu lama.

      Untuk mempermudah proses ini, Intlayer mengusulkan compiler / extractor untuk mengubah komponen Anda dan mengekstrak konten.

      Untuk menyiapkannya, Anda dapat menambahkan bagian compiler di file intlayer.config.ts Anda:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... sisa konfigurasi Anda  compiler: {    /**     * Menandakan apakah kompiler harus diaktifkan.     */    enabled: true,    /**     * Menentukan jalur file output     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Menandakan apakah komponen harus disimpan setelah diubah.     * Dengan begitu, kompiler hanya perlu dijalankan sekali untuk mengubah aplikasi, dan kemudian dapat dihapus.     */    saveComponents: false,    /**     * Awalan kunci kamus     */    dictionaryKeyPrefix: "",  },};export default config;

    (Opsional) Sitemap dan robots.txt (generate saat build)

    Intlayer menyediakan generateSitemap dan getMultilingualUrls untuk memformat sitemap.xml multibahasa dan robots.txt yang siap untuk crawler, lalu menulisnya secara otomatis ke public/. Biasanya skrip Node kecil dijalankan sebelum Vite (misalnya hook npm predev / prebuild).

    Sitemap

    Generator sitemap Intlayer menghormati konfigurasi locale dan menambahkan metadata untuk crawler.

    Sitemap mendukung namespace xhtml:link (hreflang). Alih-alih hanya daftar URL datar, Intlayer menghubungkan semua varian bahasa setiap halaman secara dua arah (mis. /about, /fr/about, atau /about?lang=fr tergantung mode routing).

    Robots.txt

    Gunakan getMultilingualUrls agar aturan Disallow mencakup semua varian URL jalur sensitif.

    1. Buat generate-seo.mjs di root proyek

    generate-seo.mjs
    import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

    Paket intlayer harus terpasang. Setel SITE_URL di lingkungan produksi (misalnya di CI).

    Disarankan generate-seo.mjs untuk ESM Node. Jika memakai generate-seo.js, pastikan "type": "module" di package.json atau aktifkan ESM lainnya.

    2. Jalankan skrip sebelum Vite

    package.json
    {  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

    Sesuaikan perintah jika memakai pnpm atau yarn. Skrip juga bisa dipanggil dari CI.

    Konfigurasi TypeScript

    Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dibuat secara otomatis.

    tsconfig.json
    {  "compilerOptions": {    // ...    "experimentalDecorators": true,    "useDefineForClassFields": false,  },  "include": ["src", ".intlayer/**/*.ts"],}
    experimentalDecorators dan useDefineForClassFields: false diperlukan oleh Lit untuk dukungan dekorator.

    Konfigurasi Git

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

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

    bash
    # Abaikan file yang dihasilkan oleh Intlayer.intlayer

    Ekstensi VS Code

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

    Instal dari VS Code Marketplace

    Ekstensi ini menyediakan:

    • Pelengkapan otomatis untuk kunci terjemahan.
    • Deteksi kesalahan waktu nyata untuk terjemahan yang hilang.
    • Pratinjau sebaris dari konten yang diterjemahkan.
    • Tindakan cepat untuk membuat dan memperbarui terjemahan dengan mudah.

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

    Melangkah Lebih Jauh

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

    Vite dan Vanilla JS
    Angular 21