Creation:2026-04-24Last update:2026-05-31

    Terjemahkan Situs Astro + Preact Anda dengan Intlayer | Internasionalisasi (i18n)

    ide.intlayer.org

    Daftar Isi

    Mengapa Intlayer dibandingkan alternatif?

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

    Intlayer dioptimalkan untuk bekerja sempurna dengan Astro dengan menawarkan perutean multibahasa, peta situs, 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 Mengonfigurasi Intlayer di Astro + Preact

    Lihat templat aplikasi di GitHub.

    1. Instal Dependensi

      Instal paket yang diperlukan menggunakan manajer paket pilihan Anda:

      bash
      npm install intlayer astro-intlayer preact preact-intlayer @astrojs/preactnpx intlayer init

      • intlayer Paket inti yang menyediakan alat i18n untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpilasyon, dan perintah CLI.

      • astro-intlayer Plugin integrasi Astro untuk menghubungkan Intlayer dengan bundler Vite; juga mencakup middleware untuk mendeteksi bahasa pilihan pengguna, mengelola cookie, dan menangani pengalihan URL.

      • preact Paket inti Preact - alternatif yang cepat dan ringan untuk React.

      • preact-intlayer Paket untuk mengintegrasikan Intlayer ke dalam aplikasi Preact. Paket ini menyediakan IntlayerProvider serta hook useIntlayer dan useLocale untuk internasionalisasi di Preact.

      • @astrojs/preact Integrasi resmi Astro yang memungkinkan penggunaan island komponen Preact.

    2. Konfigurasikan Proyek Anda

      Buat file konfigurasi untuk menentukan bahasa aplikasi Anda:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      Locales.INDONESIAN,      // Bahasa Anda yang lain    ],    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, menonaktifkan log Intlayer di konsole, dan banyak lagi. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.

    3. Integrasikan Intlayer ke dalam konfigurasi Astro Anda

      Tambahkan plugin intlayer ke konfigurasi Astro Anda dan integrasi Preact.

      astro.config.ts
      // @ts-checkimport { intlayer } from "astro-intlayer";import preact from "@astrojs/preact";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer(), preact()],});
      Plugin integrasi intlayer() digunakan untuk mengintegrasikan Intlayer dengan Astro. Plugin ini memastikan pembuatan file deklarasi konten dan memantaunya dalam mode pengembangan. Plugin ini mendefinisikan variabel lingkungan Intlayer di dalam aplikasi Astro dan menyediakan alias untuk mengoptimalkan kinerja.
      Integrasi preact() memungkinkan penggunaan island komponen Preact melalui client:only="preact".

    4. Deklarasikan Konten Anda

      Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

      src/app.content.tsx
      import { h } from "preact";import { t, type Dictionary } from "intlayer";import type { ComponentChildren } from "preact";const appContent = {  key: "app",  content: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      id: "Halo Dunia",    }),  },} satisfies Dictionary;export default appContent;
      Deklarasi konten dapat didefinisikan di mana saja dalam aplikasi Anda, asalkan disertakan dalam contentDir (secara default ./src) dan cocok dengan ekstensi file deklarasi konten (secara default .content.{json,ts,tsx,js,jsx,mjs,cjs}).
      Untuk informasi selengkapnya, lihat dokumentasi deklarasi konten.
      Jika file konten Anda mengandung kode TSX, Anda mungkin perlu mengimpor import { h } from "preact"; atau memastikan pragma JSX Anda dikonfigurasi dengan benar untuk Preact.

    5. Menggunakan Konten di Astro

      Anda dapat mengonsumsi kamus langsung di file .astro menggunakan pembantu inti yang diekspor dari intlayer. Anda juga harus menambahkan metadata SEO (seperti hreflang dan tautan kanonikal) di setiap halaman dan memperkenalkan island Preact untuk konten interaktif di sisi klien.

      src/pages/[...locale]/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";import { PreactIsland } from "../../components/preact/ReactIsland";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { title } = getIntlayer("app", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{title}</title>    <!-- Tautan Kanonikal: Memberitahu mesin pencari tentang versi utama halaman ini -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang: Memberitahu Google tentang semua versi yang dilokalkan -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <!-- x-default: Opsi fallback saat bahasa tidak cocok dengan bahasa pengguna -->    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <!-- Island Preact merender semua konten interaktif, termasuk pengalih bahasa -->    <PreactIsland locale={locale} client:only="preact" />  </body></html>
      Jika Anda ingin menggunakan konten Anda dalam atribut string, seperti alt, title, href, aria-label, dll., Anda dapat menggunakan nilai fungsi, seperti:
      html
      <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

      Catatan tentang Penyiapan Perutean: Struktur direktori yang Anda gunakan bergantung pada pengaturan middleware.routing di intlayer.config.ts:

      • prefix-no-default (default): Mempertahankan bahasa default di root (tanpa awalan) dan mengawali bahasa lainnya. Gunakan [...locale] untuk menangkap semua kasus.
      • prefix-all: Semua URL mendapatkan awalan bahasa. Anda dapat menggunakan [locale] standar jika tidak perlu menangani root secara terpisah.
      • search-param atau no-prefix: Direktori bahasa tidak diperlukan. Bahasa dikelola melalui parameter kueri atau cookie.

    6. Membuat Komponen Island Preact

      Buat komponen island yang membungkus aplikasi Preact Anda dan menerima bahasa yang dideteksi server:

      src/components/preact/PreactIsland.tsx
      /** @jsxImportSource preact */import { IntlayerProvider, useIntlayer } from "preact-intlayer";import { type LocalesValues } from "intlayer";import type { FunctionalComponent } from "preact";import { LocaleSwitcher } from "./LocaleSwitcher";const App: FunctionalComponent = () => {  const { title } = useIntlayer("app");  return (    <div>      <h1>{title}</h1>      <LocaleSwitcher />    </div>  );};export const PreactIsland: FunctionalComponent<{ locale: LocalesValues }> = ({  locale,}) => (  <IntlayerProvider locale={locale}>    <App />  </IntlayerProvider>);
      Prop locale diteruskan dari halaman Astro (deteksi sisi server) ke IntlayerProvider, yang berfungsi sebagai bahasa awal untuk semua hook Preact di dalam pohon.
      Catatan: Di Preact, atribut HTML class digunakan alih-alih className.

    7. Menambahkan Pengalih Bahasa

      Buat komponen Preact LocaleSwitcher yang membaca bahasa yang tersedia dan menavigasi ke URL yang dilokalkan saat pengguna memilih bahasa baru:

      src/components/preact/LocaleSwitcher.tsx
      /** @jsxImportSource preact */import { useLocale } from "preact-intlayer";import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";import type { FunctionalComponent } from "preact";export const LocaleSwitcher: FunctionalComponent = () => {  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      // Navigasi ke URL yang dilokalkan saat perubahan bahasa      window.location.href = getLocalizedUrl(        window.location.pathname,        newLocale      );    },  });  return (    <div class="locale-switcher">      <span class="switcher-label">Ganti bahasa:</span>      <div class="locale-buttons">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            onClick={() => setLocale(localeItem)}            class={`locale-btn ${localeItem === locale ? "active" : ""}`}            disabled={localeItem === locale}          >            <span class="ls-own-name">{getLocaleName(localeItem)}</span>            <span class="ls-current-name">              {getLocaleName(localeItem, locale)}            </span>            <span class="ls-code">{localeItem.toUpperCase()}</span>          </button>        ))}      </div>    </div>  );};

      Catatan tentang Persistensi: Menggunakan onLocaleChange untuk mengarahkan ulang melalui window.location.href memastikan bahwa URL bahasa baru dikunjungi. Hal ini memungkinkan middleware Intlayer menyetel cookie bahasa dan mengingat preferensi pengguna untuk kunjungan mendatang.

      LocaleSwitcher harus dirender di dalam IntlayerProvider - gunakan ini di komponen island Anda (seperti yang ditunjukkan pada Langkah 6).

    8. Sitemap dan Robots.txt

      Intlayer menawarkan utilitas untuk secara dinamis membuat peta situs yang dilokalkan dan file robots.txt Anda.

      Sitemap

      Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

      The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

      Buat src/pages/sitemap.xml.ts untuk menghasilkan peta situs yang mencakup semua rute yang dilokalkan.

      src/pages/sitemap.xml.ts
      import type { APIRoute } from "astro";import { generateSitemap, type SitemapUrlEntry } from "intlayer";const pathList: SitemapUrlEntry[] = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";export const GET: APIRoute = async ({ site }) => {  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });  return new Response(xmlOutput, {    headers: { "Content-Type": "application/xml" },  });};

      Robots.txt

      Buat src/pages/robots.txt.ts untuk mengontrol perayapan mesin pencari.

      src/pages/robots.txt.ts
      import type { APIRoute } from "astro";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);export const GET: APIRoute = ({ site }) => {  const robotsTxt = [    "User-agent: *",    "Allow: /",    ...disallowedPaths.map((path) => `Disallow: ${path}`),    "",    `Sitemap: ${new URL("/sitemap.xml", site).href}`,  ].join("\n");  return new Response(robotsTxt, {    headers: { "Content-Type": "text/plain" },  });};

    9. Ekstrak konten komponen Anda

      Opsional

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

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

      Untuk mengaturnya, 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: {
    /**
     * Menunjukkan apakah compiler harus diaktifkan.
     */
    enabled: true,

    /**
     * Menentukan jalur file output
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Menunjukkan apakah komponen harus disimpan setelah diubah. Dengan begitu, compiler dapat dijalankan satu kali saja untuk mengubah aplikasi, lalu dapat dihapus.
     */
    saveComponents: false,

    /**
     * Prefiks kunci kamus
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Jalankan extractor untuk mengubah komponen Anda dan mengekstrak kontennya

      bash
      npx intlayer extract

    Konfigurasi TypeScript

    Intlayer menggunakan augmentasi modul (module augmentation) untuk memanfaatkan TypeScript, membuat basis kode Anda lebih kuat. Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dibuat secara otomatis dan dikonfigurasi untuk Preact:

    tsconfig.json
    {  compilerOptions: {    // ...    jsx: "react-jsx",    jsxImportSource: "preact", // Direkomendasikan untuk Preact 10+  },  "include": [    // ... konfigurasi TypeScript Anda yang sudah ada    ".intlayer/**/*.ts", // Sertakan tipe yang dibuat secara otomatis  ],}

    Konfigurasi Git

    Disarankan untuk mengabaikan file yang dihasilkan oleh Intlayer. Ini mencegah file tersebut di-commit ke repositori Git Anda.

    Untuk melakukannya, tambahkan instruksi 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 ekstensi resmi Intlayer untuk VS Code.

    Instalasi dari VS Code Marketplace

    Ekstensi ini menyediakan:

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

    Untuk informasi selengkapnya tentang cara menggunakan ekstensi, lihat dokumentasi ekstensi VS Code.

    Perdalam Pengetahuan Anda

    Jika Anda ingin mempelajari lebih lanjut, Anda juga dapat menerapkan Editor Visual atau menggunakan CMS untuk mengeksternalisasi konten Anda.

    Astro dan Solid
    Astro dan Lit