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

Daftar Isi

Apa itu Intlayer?

Intlayer adalah perpustakaan 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, meningkatkan pelengkapan otomatis dan deteksi kesalahan.
• Memanfaatkan fitur-fitur canggih, seperti deteksi dan pengalihan bahasa dinamis.

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

Langkah 1: Instal Dependensi

Instal paket-paket yang diperlukan menggunakan npm:

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.

Langkah 2: Konfigurasi Proyek Anda

Buat file konfigurasi untuk menyiapkan bahasa aplikasi Anda:

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.

Langkah 3: Integrasikan Intlayer ke dalam Konfigurasi Vite Anda

Tambahkan plugin intlayer ke konfigurasi Anda.

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.

Langkah 4: Bootstrap Intlayer di Entry Point Anda

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

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:

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

Langkah 5: Deklarasikan Konten Anda

Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

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

Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

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

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

Salin konten

Salin kode

Salin kode ke clipboard

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

(Opsional) Langkah 7: Ubah Bahasa Konten Anda

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

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>    `;  }}

(Opsional) Langkah 8: Render Konten Markdown dan HTML

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

Render HTML terkompilasi di elemen Anda:

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.

(Opsional) Langkah 9: Tambahkan Perutean Terlokalisasi ke Aplikasi Anda

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.

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

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

(Opsional) Langkah 10: Ubah URL saat Bahasa Berubah

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

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>    `;  }}

(Opsional) Langkah 11: Alihkan Atribut Bahasa dan Arah HTML

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

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 -->`;  }}

(Opsional) Langkah 12: Ekstrak Konten Komponen Anda

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:

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

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.

Konfigurasi TypeScript

Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dibuat secara otomatis.

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

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