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

Daftar Isi

Apa itu Intlayer?

Intlayer adalah pustaka internasionalisasi (i18n) sumber terbuka yang inovatif yang dirancang untuk menyederhanakan 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 dibuat secara otomatis untuk pelengkapan otomatis dan deteksi kesalahan yang lebih baik.
• Memanfaatkan fitur-fitur canggih: Seperti deteksi bahasa dinamis dan peralihan bahasa.

Panduan Langkah-demi-Langkah untuk Mengonfigurasi Intlayer di Astro + Vanilla JS

Lihat templat aplikasi di GitHub.

Langkah 1: Instal Dependensi

Instal paket yang diperlukan menggunakan manajer paket pilihan Anda:

npm install intlayer astro-intlayer vanilla-intlayernpx intlayer init

• intlayer Paket inti yang menyediakan alat i18n untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpilasi, 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.

• vanilla-intlayer Paket untuk mengintegrasikan Intlayer ke dalam aplikasi Vanilla JavaScript / TypeScript. Paket ini menyediakan singleton Pub/Sub (IntlayerClient) dan pembantu berbasis callback (useIntlayer, useLocale, dll.) agar bagian mana pun dari Astro <script> Anda dapat bereaksi terhadap perubahan bahasa tanpa memerlukan framework UI.

Langkah 2: Konfigurasikan Proyek Anda

Buat file konfigurasi untuk menentukan bahasa aplikasi Anda:

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.

Langkah 3: Integrasikan Intlayer ke dalam konfigurasi Astro Anda

Tambahkan plugin intlayer ke konfigurasi Astro Anda. Tidak diperlukan integrasi framework UI tambahan untuk Vanilla JS.

// @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer()],});

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.

Langkah 4: Deklarasikan Konten Anda

Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      id: "Halo Dunia",    }),    description: t({      en: "Welcome to my multilingual Astro site.",      fr: "Bienvenue sur mon site Astro multilingue.",      es: "Bienvenido a mi sitio Astro multilingüe.",      id: "Selamat datang di situs Astro multibahasa saya.",    }),    switchLocale: t({      en: "Switch language:",      fr: "Changer de langue :",      es: "Cambiar idioma:",      id: "Ganti bahasa:",    }),  },} 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.

Langkah 5: Menggunakan Konten di Astro

Dengan Vanilla JS, semua server-side rendering (SSR) terjadi langsung di file .astro menggunakan getIntlayer. Kemudian, di sisi klien, blok <script> menginisialisasi pustaka vanilla-intlayer untuk mengaktifkan peralihan bahasa.

---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getPrefix,  getLocaleName,  localeMap,  locales,  defaultLocale,  getPathWithoutLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);const { greeting, description, switchLocale } = 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>{greeting}</title>    <!-- Tautan Kanonikal -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Tautan Hreflang -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <main>      <h1 id="greeting">{greeting}</h1>      <p id="description">{description}</p>      <div class="locale-switcher">        <span class="switcher-label">{switchLocale}</span>        <div class="locale-buttons">          {            locales.map((localeItem) => (              <a                href={localeItem === locale ? undefined : getLocalizedUrl(pathWithoutLocale, localeItem)}                class={`locale-btn ${localeItem === locale ? "active" : ""}`}                data-locale={localeItem}                aria-disabled={localeItem === locale}              >                {getLocaleName(localeItem)}              </a>            ))          }        </div>      </div>    </main>  </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

Salin konten

Salin kode

Salin kode ke clipboard

<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.

Langkah 6: Menambahkan Pengalih Bahasa

Di Astro dengan Vanilla JS, pengalih bahasa dihasilkan di server sebagai tautan biasa dan diaktifkan di sisi klien melalui blok <script>. Saat pengguna mengklik tautan bahasa, vanilla-intlayer menyetel cookie bahasa melalui setLocale sebelum menavigasi ke URL yang dilokalkan.

<!-- Sertakan markup sisi server dari Langkah 5 di sini --><script>  import { installIntlayer, useLocale } from "vanilla-intlayer";  import { getLocaleFromPath, getLocalizedUrl, type LocalesValues } from "intlayer";  // Inisialisasi Intlayer di klien dengan bahasa yang diambil dari jalur saat ini  const locale = getLocaleFromPath(window.location.pathname);  installIntlayer({ locale: locale as LocalesValues });  const { setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      window.location.href = getLocalizedUrl(window.location.pathname, newLocale);    },  });  // Hubungkan peristiwa klik pada tautan pengalih bahasa  const localeLinks = document.querySelectorAll("[data-locale]");  localeLinks.forEach((link) => {    link.addEventListener("click", (e) => {      const localeValue = link.getAttribute("data-locale") as LocalesValues;      if (localeValue && localeValue !== locale) {        e.preventDefault();        setLocale(localeValue);      }    });  });</script>

Catatan tentang Persistensi: installIntlayer menginisialisasi singleton Intlayer dengan bahasa yang ditentukan server. useLocale bersama dengan onLocaleChange memastikan bahwa cookie bahasa disetel sebelum pengalihan melalui middleware, memungkinkan preferensi bahasa pengguna diingat untuk kunjungan mendatang.

Catatan tentang Progressive Enhancement: Tautan di dalam pengalih bahasa akan berfungsi sebagai tag <a> standar bahkan tanpa JavaScript. Saat JavaScript tersedia, panggilan setLocale memperbarui cookie sebelum mengarahkan ulang, memastikan middleware menangani pilihan bahasa dengan benar.

Langkah 7: 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.

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.

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

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.

{  // ... konfigurasi TypeScript Anda yang sudah ada  "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:

# 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.

(Opsional) Langkah 1 : Ekstrak konten komponen Anda

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:

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;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Menambahkan plugin compiler ],});

npm run build # Atau npm run dev

Perdalam Pengetahuan Anda

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