Terjemahkan situs web Vite dan Solid Anda menggunakan Intlayer | Internasionalisasi (i18n)

Table of Contents

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

Apa itu Intlayer?

Intlayer adalah pustaka internasionalisasi (i18n) open-source 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.
• Menjamin 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 Vite dan Solid

Daftar Isi

Langkah 1: Instalasi Dependensi

Instal paket yang diperlukan menggunakan npm:

npm install intlayer solid-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer

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

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

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

Langkah 2: Konfigurasi proyek Anda

Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Bahasa 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 Vite Anda

Tambahkan plugin intlayer ke dalam konfigurasi Anda.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), 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.

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: {},
} satisfies Dictionary;

export default appContent;

Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama file tersebut dimasukkan ke dalam direktori contentDir (secara default, ./src). Dan sesuai dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

Langkah 5: Gunakan Intlayer dalam Kode Anda

Akses kamus konten Anda di seluruh aplikasi:

import { createSignal, type Component } from "solid-js";import solidLogo from "./assets/solid.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "solid-intlayer";const AppContent: Component = () => {  const [count, setCount] = createSignal(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://www.solidjs.com/" target="_blank">          <img            src={solidLogo}            class="logo solid"            alt={content.solidLogo.value}          />        </a>      </div>      <h1>{content.title}</h1>      <div class="card">        <button onClick={() => setCount((count) => count + 1)}>          {content.count({ count: count() })}        </button>        <p>{content.edit}</p>      </div>      <p class="read-the-docs">{content.readTheDocs}</p>    </>  );};const App: Component = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

Di Solid, useIntlayer mengembalikan fungsi accessor (misalnya, `content.). Anda harus memanggil fungsi ini untuk mengakses konten reaktif.

Jika Anda ingin menggunakan konten Anda dalam atribut string, seperti alt, title, href, aria-label, dll., Anda harus memanggil 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)}" />

(Opsional) Langkah 6: Ubah bahasa konten Anda

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 sesuai dengan itu.

import { type Component, For } from "solid-js";import { Locales } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const { locale, setLocale, availableLocales } = useLocale();  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as Locales)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

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

Tujuan dari langkah ini adalah membuat rute unik untuk setiap bahasa. Ini berguna untuk SEO dan URL yang ramah SEO. Contoh:

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

Untuk menambahkan routing yang dilokalkan ke aplikasi Anda, Anda dapat menggunakan @solidjs/router.

Pertama, instal dependensi yang diperlukan:

npm install @solidjs/router

Kemudian, bungkus aplikasi Anda dengan Router dan definisikan rute Anda menggunakan localeMap:

import { render } from "solid-js/web";import { Router } from "@solidjs/router";import App from "./App";const root = document.getElementById("root");render(  () => (    <Router>      <App />    </Router>  ),  root!);

import { type Component } from "solid-js";import { Route } from "@solidjs/router";import { localeMap } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import Home from "./pages/Home";import About from "./pages/About";const App: Component = () => (  <IntlayerProvider>    {localeMap(({ locale, urlPrefix }) => (      <Route        path={urlPrefix || "/"}        component={(props: any) => (          <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>        )}      >        <Route path="/" component={Home} />        <Route path="/about" component={About} />      </Route>    ))}  </IntlayerProvider>);export default App;

(Opsional) Langkah 8: Ubah URL saat locale berubah

Untuk mengubah URL saat locale berubah, Anda dapat menggunakan prop onLocaleChange yang disediakan oleh hook useLocale. Anda dapat menggunakan hook useNavigate dan useLocation dari @solidjs/router untuk memperbarui jalur URL.

import { type Component, For } from "solid-js";import { useLocation, useNavigate } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const location = useLocation();  const navigate = useNavigate();  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (loc) => {      const pathWithLocale = getLocalizedUrl(location.pathname, loc);      navigate(pathWithLocale);    },  });  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as any)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

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

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

import { createEffect, type Component } from "solid-js";import { useLocale } from "solid-intlayer";import { getHTMLTextDir } from "intlayer";const AppContent: Component = () => {  const { locale } = useLocale();  createEffect(() => {    document.documentElement.lang = locale();    document.documentElement.dir = getHTMLTextDir(locale());  });  return (    // ... Konten aplikasi Anda  );};

(Opsional) Langkah 10: Membuat Komponen Link yang Dilokalkan

Buat komponen Link kustom yang secara otomatis menambahkan prefiks URL internal dengan bahasa saat ini.

import { type ParentComponent } from "solid-js";import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const Link: ParentComponent<AnchorProps> = (props) => {  const { locale } = useLocale();  const isExternal = () => props.href.startsWith("http");  const localizedHref = () =>    isExternal() ? props.href : getLocalizedUrl(props.href, locale());  return <A {...props} href={localizedHref()} />;};

(Opsional) Langkah 11: Render Markdown

Intlayer mendukung rendering konten Markdown langsung di aplikasi Solid Anda menggunakan parser internalnya sendiri. Secara default, Markdown diperlakukan sebagai teks biasa. Untuk merender sebagai HTML yang kaya, bungkus aplikasi Anda dengan MarkdownProvider.

import { render } from "solid-js/web";import { MarkdownProvider } from "solid-intlayer/markdown";import App from "./App";const root = document.getElementById("root");render(  () => (    <MarkdownProvider>      <App />    </MarkdownProvider>  ),  root!);

Kemudian Anda dapat menggunakannya di komponen Anda:

import { useIntlayer } from "solid-intlayer";const MyComponent = () => {  const content = useIntlayer("my-content");  return (    <div>      {/* Render sebagai HTML melalui MarkdownProvider */}      {content.markdownContent}    </div>  );};

Konfigurasi TypeScript

Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan otomatis.

{  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

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 yang diterjemahkan.
• Aksi cepat untuk dengan mudah membuat dan memperbarui terjemahan.

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

(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

(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: 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

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

Melangkah Lebih Jauh

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