Terjemahkan situs web Vite dan Preact Anda menggunakan Intlayer

Daftar Isi

Mengapa Intlayer dibandingkan alternatif?

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

Panduan Langkah demi Langkah untuk Mengatur Intlayer dalam Aplikasi Vite dan Preact

Lihat Template Aplikasi di GitHub.

1. 1

   Instalasi Dependensi

   Instal paket yang diperlukan menggunakan npm:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   npx intlayer init --interactive
   

   flag --interactive bersifat opsional. Gunakan intlayer-cli init jika Anda adalah agen AI.

   Perintah ini akan mendeteksi lingkungan Anda dan menginstal paket yang diperlukan. Misalnya:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   npm install intlayer preact-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • vite-intlayer

     Termasuk plugin Vite untuk mengintegrasikan Intlayer dengan Vite bundler, serta middleware untuk mendeteksi locale yang dipilih pengguna, mengelola cookie, dan menangani pengalihan URL.

2. 2

   Konfigurasi proyek Anda

   Arsitektur

   Dalam arsitektur ini, preact-intlayer menyediakan IntlayerProvider yang dipasang di main.tsx untuk membungkus hierarki Preact. Deklarasi konten berada di src/ di samping komponen.

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   .
   ├── src
   │   ├── app.content.tsx
   │   ├── app.css
   │   ├── app.tsx                       # Main Preact application component
   │   ├── components
   │   │   ├── LocaleSwitcher.content.ts
   │   │   └── LocaleSwitcher.tsx
   │   ├── main.tsx                      # Entry point with IntlayerProvider
   │   └── vite-env.d.ts
   ├── index.html
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

   Konfigurasi

   Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

   intlayer.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Locale lain milik Anda
       ],
       defaultLocale: Locales.ENGLISH,
     },
     routing: {
       mode: "prefix-no-default", // Default: prefix semua locale kecuali locale default
       storage: ["cookie", "header"], // Default: simpan locale di cookie dan deteksi dari header
     },
   };
   
   export default config;
   

   Melalui file konfigurasi ini, Anda dapat mengatur URL yang dilokalkan, mode routing, opsi penyimpanan, nama cookie, lokasi dan ekstensi deklarasi konten Anda, menonaktifkan log Intlayer di konsol, dan lainnya. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.

   dokumentasi konfigurasi
3. 3

   Integrasikan Intlayer dalam Konfigurasi Vite Anda

   Tambahkan plugin intlayer ke trong konfigurasi Anda.

   vite.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { defineConfig } from "vite";
   import preact from "@preact/preset-vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [preact(), intlayer()],
   });
   

   Plugin Vite intlayer() digunakan untuk mengintegrasikan Intlayer dengan Vite. Plugin ini memastikan pembuatan file deklarasi konten dan memantau file tersebut dalam mode pengembangan. Plugin ini juga mendefinisikan variabel lingkungan Intlayer di dalam aplikasi Vite. Selain itu, plugin ini menyediakan alias untuk mengoptimalkan performa.

4. 4

   Deklarasikan Konten Anda

   Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

   src/app.content.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { t, type Dictionary } from "intlayer";
   import type { ComponentChildren } from "preact";
   
   const appContent = {
     key: "app",
     content: {
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       preactLogo: t({
         en: "Preact logo",
         fr: "Logo Preact",
         es: "Logo Preact",
       }),
   
       title: "Vite + Preact",
   
       count: t({
         en: "count is ",
         fr: "le compte est ",
         es: "el recuento es ",
       }),
   
       edit: t<ComponentChildren>({
         en: (
           <>
             Edit <code>src/app.tsx</code> and save to test HMR
           </>
         ),
         fr: (
           <>
             Éditez <code>src/app.tsx</code> et enregistrez pour tester HMR
           </>
         ),
         es: (
           <>
             Edita <code>src/app.tsx</code> y guarda para probar HMR
           </>
         ),
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and Preact logos to learn more",
         fr: "Cliquez sur les logos Vite et Preact pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y Preact para obtener más información",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama berada di 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.

   dokumentasi deklarasi konten

   Jika file konten Anda menyertakan kode TSX, Anda mungkin perlu mengimpor import { h } from "preact"; atau memastikan pragma JSX Anda sudah diatur dengan benar untuk Preact.

5. 5

   Gunakan Intlayer dalam Kode Anda

   Akses kamus konten Anda di seluruh aplikasi:

   src/app.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { useState } from "preact/hooks";
   import type { FunctionalComponent } from "preact";
   import preactLogo from "./assets/preact.svg"; // Mengasumsikan Anda memiliki preact.svg
   import viteLogo from "/vite.svg";
   import "./app.css"; // Mengasumsikan file CSS Anda bernama app.css
   import { IntlayerProvider, useIntlayer } from "preact-intlayer";
   
   const AppContent: FunctionalComponent = () => {
     const [count, setCount] = useState(0);
     const content = useIntlayer("app");
   
     return (
       <>
         <div>
           <a href="https://vitejs.dev" target="_blank">
             <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
           </a>
           <a href="https://preactjs.com" target="_blank">
             <img
               src={preactLogo}
               class="logo preact"
               alt={content.preactLogo.value}
             />
           </a>
         </div>
         <h1>{content.title}</h1>
         <div class="card">
           <button onClick={() => setCount((count) => count + 1)}>
             {content.count}
             {count}
           </button>
           <p>{content.edit}</p>
         </div>
         {/* Konten Markdown */}
         <div>{content.myMarkdownContent}</div>
   
         {/* Konten HTML */}
         <div>{content.myHtmlContent}</div>
   
         <p class="read-the-docs">{content.readTheDocs}</p>
       </>
     );
   };
   
   const App: FunctionalComponent = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;
   

   Jika Anda ingin menggunakan konten Anda dalam atribut string, seperti alt, title, href, aria-label, dll., Anda harus memanggil nilai fungsi tersebut, seperti:

   tsx

   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: Dalam Preact, className biasanya ditulis sebagai class.

   Untuk mempelajari lebih lanjut tentang hook useIntlayer, lihat dokumentasi (API-nya serupa untuk preact-intlayer).

   Dokumentasi Hook useIntlayer | react-intlayer

   Jika aplikasi Anda sudah ada, Anda dapat menggunakan Intlayer Compiler secara kombinasi dengan perintah extract untuk mengonversi ribuan komponen dalam satu detik.

   Intlayer Compiler

   perintah extract
6. 6

   Ubah bahasa konten Anda

   Opsional

   Untuk mengubah bahasa konten Anda, Anda dapat menggunakan fungsi setLocale yang disediakan oleh hook useLocale. Fungsi ini memungkinkan Anda mengatur locale aplikasi dan memperbarui konten yang sesuai.

   src/components/LocaleSwitcher.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { FunctionalComponent } from "preact";
   import { Locales } from "intlayer";
   import { useLocale } from "preact-intlayer";
   
   const LocaleSwitcher: FunctionalComponent = () => {
     const { setLocale } = useLocale();
   
     return (
       <button onClick={() => setLocale(Locales.ENGLISH)}>
         Ubah Bahasa ke Bahasa Inggris
       </button>
     );
   };
   
   export default LocaleSwitcher;
   

   Untuk mempelajari lebih lanjut tentang hook useLocale, lihat dokumentasi (API serupa untuk preact-intlayer).

   Dokumentasi Hook useLocale | react-intlayer
7. 7

   Tambahkan Perutean yang Dilokalkan ke aplikasi Anda

   Opsional

   Tujuan dari langkah ini adalah untuk membuat rute unik cho mỗi ngôn ngữ. Điều này hữu ích cho SEO và các URL thân thiện với SEO. Ví dụ:

   plaintext

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   Secara default, rute tidak diberi awalan untuk locale default. Jika Anda ingin menambahkan prefix untuk locale default, Anda dapat mengatur opsi routing.mode menjadi "prefix-all" dalam konfigurasi Anda. Lihat dokumentasi konfigurasi untuk informasi lebih lanjut.

   dokumentasi konfigurasi

   Untuk menambahkan routing terlokalisasi ke aplikasi Anda, Anda dapat membuat komponen LocaleRouter yang membungkus rute aplikasi dan menangani routing berdasarkan locale. Berikut adalah contoh menggunakan preact-iso:

   src/components/LocaleRouter.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { localeMap } from "intlayer";
   import { IntlayerProvider } from "preact-intlayer";
   import { LocationProvider, Router, Route } from "preact-iso";
   import type { ComponentChildren, FunctionalComponent } from "preact";
   
   /**
    * Komponen routing yang mengatur rute spesifik untuk setiap locale.
    * Menggunakan preact-iso untuk mengelola navigasi dan merender komponen lokal.
    */
   export const LocaleRouter: FunctionalComponent<{
     children: ComponentChildren;
   }> = ({ children }) => (
     <LocationProvider>
       <Router>
         {localeMap(({ locale, urlPrefix }) => ({ locale, urlPrefix }))
           .sort((a, b) => b.urlPrefix.length - a.urlPrefix.length)
           .map(({ locale, urlPrefix }) => (
             <Route
               key={locale}
               path={`${urlPrefix}/:rest*`}
               component={() => (
                 <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
               )}
             />
           ))}
       </Router>
     </LocationProvider>
   );
   

   Setelah itu, Anda dapat menggunakan komponen LocaleRouter dalam aplikasi Anda:

   src/app.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { LocaleRouter } from "./components/LocaleRouter";
   import type { FunctionalComponent } from "preact";
   
   // ... Komponen AppContent Anda
   
   const App: FunctionalComponent = () => (
     <LocaleRouter>
       <AppContent />
     </LocaleRouter>
   );
   
   export default App;
   

   Secara bersamaan, Anda juga dapat menggunakan intlayerProxy untuk menambahkan routing sisi server ke aplikasi Anda. Plugin ini akan secara otomatis mendeteksi locale saat ini berdasarkan URL dan menetapkan cookie locale yang sesuai. Jika tidak ada locale yang ditentukan, plugin akan menentukan locale yang paling sesuai berdasarkan preferensi bahasa browser pengguna. Jika tidak ada locale yang terdeteksi, plugin akan mengarahkan ulang ke locale default.

   Perhatikan bahwa untuk menggunakan intlayerProxy dalam produksi, Anda perlu memindahkan paket vite-intlayer dari devDependencies ke dependencies.

   Sejak Intlayer v9, intlayerProxy() digabungkan langsung ke dalam plugin intlayer() dan diaktifkan secara default melalui opsi routing.enableProxy (true secara default). Mendaftarkannya secara terpisah seperti yang ditunjukkan di bawah ini sekarang bersifat opsional, ini dipertahankan untuk kompatibilitas mundur dan untuk setup yang perlu mengontrol urutan plugin. Atur routing.enableProxy: false untuk tidak mengikuti. Lihat catatan rilis v9.

   catatan rilis v9

   vite.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   import preact from "@preact/preset-vite";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       preact(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

8. 8

   Ubah URL saat locale berubah

   Opsional

   Untuk mengubah URL saat locale berubah, Anda dapat menggunakan properti onLocaleChange yang disediakan oleh hook useLocale. Pada saat yang sama, Anda dapat menggunakan metode route dari useLocation milik preact-iso untuk memperbarui path URL.

   src/components/LocaleSwitcher.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { useLocation } from "preact-iso";
   import {
     Locales,
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
   } from "intlayer";
   import { useLocale } from "preact-intlayer";
   import type { FunctionalComponent } from "preact";
   
   const LocaleSwitcher: FunctionalComponent = () => {
     const { url, route } = useLocation();
     const { locale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         // Buat URL dengan locale yang diperbarui
         // Contoh: /es/about?foo=bar
         const pathWithLocale = getLocalizedUrl(url, newLocale);
   
         // Perbarui path URL
         route(pathWithLocale, true); // true untuk menggantikan (replace)
       },
     });
   
     return (
       <div>
         <button popovertarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <a
               href={getLocalizedUrl(url, localeItem)}
               hreflang={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={(e) => {
                 e.preventDefault();
                 setLocale(localeItem);
                 // Navigasi terprogram setelah mengatur locale akan ditangani oleh onLocaleChange
               }}
               key={localeItem}
             >
               <span>
                 {/* Locale - misalnya: FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Bahasa dalam Locale itu sendiri - misalnya: Français */}
                 {getLocaleName(localeItem, localeItem)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Bahasa dalam Locale saat ini - misalnya: Francés dengan locale saat ini diatur ke Locales.SPANISH */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* Bahasa dalam Bahasa Inggris - misalnya: French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </a>
           ))}
         </div>
       </div>
     );
   };
   
   export default LocaleSwitcher;
   

   Lihat dokumentasi:

   • Hook useLocale (API serupa untuk preact-intlayer)> - Fungsi getLocaleName> - Fungsi getLocalizedUrl> - Fungsi getHTMLTextDir> - Atribut hreflang> - Atribut lang> - Atribut dir> - Atribut aria-current> - Popover API

   Hook useLocale

   Function getLocaleName

   Function getLocalizedUrl

   Function getHTMLTextDir

   Berikut adalah Langkah 9 yang diperbarui dengan penjelasan tambahan dan contoh kode yang disempurnakan:

9. 9

   Ganti atribut bahasa dan arah HTML

   Opsional

   Ketika aplikasi Anda mendukung banyak bahasa, memperbarui atribut lang dan dir dari tag <html> agar sesuai dengan locale saat ini sangatlah penting. Melakukan hal ini memastikan:

   • Aksesibilitas: Pembaca layar (screen reader) dan teknologi asistif bergantung pada atribut lang yang tepat untuk melafalkan dan menginterpretasikan konten dengan benar.
   • Rendering Teks: Atribut dir (arah teks) memastikan teks ditampilkan dalam urutan yang tepat (misalnya: kiri-ke-kanan untuk bahasa Inggris/Indonesia, kanan-ke-kiri untuk bahasa Arab atau Ibrani), yang sangat penting untuk keterbacaan.
   • SEO: Mesin pencari menggunakan atribut lang untuk menentukan bahasa halaman Anda, membantu menyajikan konten lokal yang tepat dalam hasil pencarian.

   Dengan memperbarui atribut-atribut ini secara dinamis saat locale berubah, Anda memastikan pengalaman yang konsisten dan mudah diakses bagi pengguna di semua bahasa yang didukung.

   Implementasi Hook

   Buat hook kustom untuk mengelola atribut HTML. Hook ini memantau perubahan locale dan memperbarui atribut yang sesuai:

   src/hooks/useI18nHTMLAttributes.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { useEffect } from "preact/hooks";
   import { useLocale } from "preact-intlayer";
   import { getHTMLTextDir } from "intlayer";
   
   /**
    * Cập nhật các thuộc tính `lang` và `dir` của phần tử HTML <html> dựa trên ngôn ngữ hiện tại.
    * - `lang`: Thông báo cho trình duyệt và công cụ tìm kiếm về ngôn ngữ của trang.
    * - `dir`: Đảm bảo thứ tự đọc chính xác (ví dụ: 'ltr' cho tiếng Anh, 'rtl' cho tiếng Ả Rập).
    *
    * Bản cập nhật động này rất cần thiết để hiển thị văn bản, khả năng truy cập và SEO thích hợp.
    */
   export const useI18nHTMLAttributes = () => {
     const { locale } = useLocale();
   
     useEffect(() => {
       // Perbarui atribut bahasa menjadi locale saat ini.
       document.documentElement.lang = locale;
   
       // Atur arah teks berdasarkan locale saat ini.
       document.documentElement.dir = getHTMLTextDir(locale);
     }, [locale]);
   };
   

   Gunakan Hook dalam Aplikasi Anda

   Integrasikan hook ke dalam komponen utama Anda agar atribut HTML diperbarui setiap kali locale berubah:

   src/app.tsx

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { FunctionalComponent } from "preact";
   import { IntlayerProvider } from "preact-intlayer"; // useIntlayer diimpor jika AppContent membutuhkannya
   import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
   import "./app.css";
   // Definisikan AppContent dari Langkah 5
   
   const AppWithHooks: FunctionalComponent = () => {
     // Terapkan hook untuk memperbarui atribut lang dan dir tag <html> berdasarkan locale.
     useI18nHTMLAttributes();
   
     // Anggap AppContent adalah komponen yang menampilkan konten utama Anda dari Langkah 5
     return <AppContent />;
   };
   
   const App: FunctionalComponent = () => (
     <IntlayerProvider>
       <AppWithHooks />
     </IntlayerProvider>
   );
   
   export default App;
   

   Dengan menerapkan perubahan-perubahan ini, aplikasi Anda akan:

   • Pastikan atribut language (lang) dengan benar mencerminkan locale saat ini, yang penting untuk SEO dan perilaku browser.
   • Sesuaikan text direction (dir) menurut locale, meningkatkan keterbacaan dan kegunaan untuk bahasa dengan urutan baca yang berbeda.
   • Sediakan pengalaman yang lebih accessible, karena teknologi assistive bergantung pada atribut ini untuk berfungsi secara optimal.
10. 10

    Membuat Komponen Link yang Dilokalkan

    Opsional

    Untuk memastikan navigasi aplikasi Anda mengikuti locale saat ini, Anda dapat membuat komponen Link kustom. Komponen ini secara otomatis menambahkan prefix locale saat ini ke URL internal.

    Perilaku ini bermanfaat karena beberapa alasan:

    • SEO dan Pengalaman Pengguna: URL yang dilokalkan membantu mesin pencari mengindeks halaman khusus bahasa dengan benar dan menyediakan konten dalam bahasa pilihan pengguna.
    • Konsistensi: Dengan menggunakan tautan terlokalisasi di seluruh aplikasi, Anda memastikan navigasi tetap berada dalam locale saat ini, mencegah perubahan bahasa yang tidak disengaja.
    • Kemudahan Pemeliharaan: Memusatkan logika lokalisasi dalam satu komponen menyederhanakan pengelolaan URL.

    Berikut cara mengimplementasikan komponen Link yang dilokalkan di Preact:

    src/components/Link.tsx

    Salin konten

    Salin kode

    Salin kode ke clipboard

    import { getLocalizedUrl } from "intlayer";
    import { useLocale } from "preact-intlayer";
    import { forwardRef } from "preact/compat";
    import type { JSX } from "preact";
    
    export interface LinkProps extends JSX.HTMLAttributes<HTMLAnchorElement> {
      href: string;
    }
    
    /**
     * Fungsi pembantu untuk memeriksa apakah URL tertentu adalah eksternal.
     * Jika URL dimulai dengan http:// atau https://, itu dianggap eksternal.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * Komponen Link kustom yang menyesuaikan atribut href berdasarkan locale saat ini.
     * Untuk tautan internal, komponen menggunakan `getLocalizedUrl` untuk menambahkan prefix locale ke URL (misalnya /fr/about).
     * Ini memastikan navigasi tetap berada dalam konteks locale yang sama.
     */
    export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
      ({ href, children, ...props }, ref) => {
        const { locale } = useLocale();
        const isExternalLink = checkIsExternalLink(href);
    
        // Jika tautan internal dan href yang valid diberikan, ambil URL yang dilokalkan.
        const hrefI18n =
          href && !isExternalLink ? getLocalizedUrl(href, locale) : href;
    
        return (
          <a href={hrefI18n} ref={ref} {...props}>
            {children}
          </a>
        );
      }
    );
    
    Link.displayName = "Link";
    

    Cara Kerjanya

    • Mendeteksi Tautan Eksternal:
      Fungsi pembantu checkIsExternalLink menentukan apakah sebuah URL adalah eksternal. Tautan eksternal dibiarkan tanpa perubahan karena tidak memerlukan lokalisasi.
    • Mengambil Locale Saat Ini:
      Hook useLocale menyediakan locale saat ini (misalnya, fr untuk bahasa Prancis).
    • Melokalkan URL:
      Untuk tautan internal (yaitu, non-eksternal), getLocalizedUrl digunakan untuk secara otomatis menambahkan prefix locale saat ini ke URL. Ini berarti jika pengguna Anda dalam bahasa Prancis, meneruskan /about sebagai href akan mengubahnya menjadi /fr/about.
    • Mengembalikan Tautan:
      Komponen mengembalikan elemen <a> dengan URL yang sudah dilokalkan, memastikan navigasi konsisten dengan locale.
11. 11

    Render Markdown dan HTML

    Opsional

    Intlayer mendukung rendering konten Markdown dan HTML dalam Preact.

    Anda dapat menyesuaikan tampilan konten Markdown dan HTML menggunakan metode .use(). Metode ini memungkinkan Anda menimpa rendering default dari tag tertentu.

    tsx

    Salin konten

    Salin kode

    Salin kode ke clipboard

    import { useIntlayer } from "preact-intlayer";
    
    const { myMarkdownContent, myHtmlContent } = useIntlayer("my-component");
    
    // ...
    
    return (
      <div>
        {/* Rendering dasar */}
        {myMarkdownContent}
    
        {/* Rendering kustom cho Markdown */}
        {myMarkdownContent.use({
          h1: (props) => <h1 style={{ color: "red" }} {...props} />,
        })}
    
        {/* Rendering dasar cho HTML */}
        {myHtmlContent}
    
        {/* Rendering kustom cho HTML */}
        {myHtmlContent.use({
          b: (props) => <strong style={{ color: "blue" }} {...props} />,
        })}
      </div>
    );
    

12. 1

    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.

    compiler

    extractor

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

    intlayer.config.ts

    Salin konten

    Salin kode

    Salin kode ke clipboard

    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;
    

    Perintah ekstrakCompiler Babel

    Jalankan extractor untuk mengubah komponen Anda dan mengekstrak kontennya

    bash

    Salin konten

    Salin kode

    Salin kode ke clipboard

    npx intlayer extract
    

    intlayer >= 9intlayer < 9

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Perbarui vite.config.ts Anda untuk menyertakan plugin intlayerCompiler:

    vite.config.ts

    Salin konten

    Salin kode

    Salin kode ke clipboard

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

    Build aplikasi Anda untuk mentransformasi komponen Anda dan mengekstrak konten

    bash

    Salin konten

    Salin kode

    Salin kode ke clipboard

    npm run build # Atau npm run dev
    

(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

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: "https://example.com",
});
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: https://example.com/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

{
  "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

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

Pastikan konfigurasi TypeScript Anda mencakup tipe yang dibuat secara otomatis.

{
  // ... Konfigurasi TypeScript Anda yang sudah ada
  "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
  ],
}

Pastikan tsconfig.json Anda diatur untuk Preact, terutama jsx dan jsxImportSource atau jsxFactory/jsxFragmentFactory untuk versi Preact yang lebih lama jika tidak menggunakan default preset-vite.

Konfigurasi Git

Disarankan untuk mengabaikan file yang dihasilkan oleh Intlayer. Ini memungkinkan Anda menghindari komitmen 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 Intlayer VS Code Extension resmi.

Extension ini menyediakan:

• Autocompletion untuk kunci terjemahan.
• Deteksi kesalahan real-time untuk terjemahan yang hilang.
• Pratinjau inline dari konten yang diterjemahkan.
• Aksi cepat untuk mudah membuat dan memperbarui terjemahan.

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

Melangkah Lebih Jauh

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

Pertanyaan yang Sering Diajukan