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

Daftar Isi

Apa itu Intlayer?

Intlayer adalah pustaka internasionalisasi (i18n) open-source yang inovatif, 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.
• Menjamin dukungan TypeScript dengan tipe yang dihasilkan secara otomatis, meningkatkan autocompletion dan deteksi kesalahan.
• Memanfaatkan fitur canggih, seperti deteksi dan pergantian locale secara dinamis.

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

Lihat Template Aplikasi di GitHub.

Langkah 1: Instalasi Dependensi

Instal paket yang diperlukan menggunakan npm:

npm install intlayer svelte-intlayernpm install vite-intlayer --save-dev

• intlayer

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

• svelte-intlayer Paket yang mengintegrasikan Intlayer dengan aplikasi Svelte. Ini menyediakan context providers dan hooks untuk internasionalisasi Svelte.

• 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,      // Locale 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 { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), 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 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: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",    }),  },} satisfies Dictionary;export default appContent;

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

Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

Langkah 5: Gunakan Intlayer dalam Kode Anda

<script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- Render konten sebagai konten sederhana  --><h1>{$content.title}</h1><!-- Untuk merender konten yang dapat diedit menggunakan editor --><h1><svelte:component this={$content.title} /></h1><!-- Untuk merender konten sebagai string --><div aria-label={$content.title.value}></div>

(Opsional) Langkah 6: Ubah bahasa konten Anda

<script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from 'svelte-intlayer';// Dapatkan informasi locale dan fungsi setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Tangani perubahan localeconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  setLocale(newLocale);};</script><div>  <select value={$locale} on:change={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

(Opsional) Langkah 7: Render Markdown

Intlayer mendukung rendering konten Markdown langsung di aplikasi Svelte Anda. Secara default, Markdown diperlakukan sebagai teks biasa. Untuk mengubah Markdown menjadi HTML kaya, Anda dapat mengintegrasikan @humanspeak/svelte-markdown, atau parser markdown lainnya.

Untuk melihat cara mendeklarasikan konten markdown menggunakan paket intlayer, lihat dokumen markdown.

<script>  import { setIntlayerMarkdown } from "svelte-intlayer";  setIntlayerMarkdown((markdown) =>   // render konten markdown sebagai string   return markdown;  );</script><h1>{$content.markdownContent}</h1>

Anda juga dapat mengakses data front-matter markdown Anda menggunakan properti content.markdownContent.metadata.xxx.

(Opsional) Langkah 8: Siapkan editor / CMS intlayer

Untuk menyiapkan editor intlayer, Anda harus mengikuti dokumentasi editor intlayer.

Untuk menyiapkan CMS intlayer, Anda harus mengikuti dokumentasi CMS intlayer.

Secara paralel, dalam aplikasi Svelte Anda, Anda harus menambahkan baris berikut di layout, atau di root aplikasi Anda:

import { useIntlayerEditor } from "svelte-intlayer";useIntlayerEditor();

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

Untuk menangani routing yang dilokalkan dalam aplikasi Svelte Anda, Anda dapat menggunakan svelte-spa-router bersama dengan localeFlatMap dari Intlayer untuk menghasilkan rute untuk setiap locale.

Pertama, instal svelte-spa-router:

npm install svelte-spa-router

Kemudian, buat file Router.svelte untuk mendefinisikan rute Anda:

<script lang="ts">import { localeFlatMap } from "intlayer";import Router from "svelte-spa-router";import { wrap } from "svelte-spa-router/wrap";import App from "./App.svelte";const routes = Object.fromEntries(    localeFlatMap(({locale, urlPrefix}) => [    [        urlPrefix || '/',        wrap({            component: App as any,            props: {                locale,            },        }),    ],    ]));</script><Router {routes} />

Perbarui main.ts Anda untuk memasang komponen Router menggantikan App:

import { mount } from "svelte";import Router from "./Router.svelte";const app = mount(Router, {  target: document.getElementById("app")!,});export default app;

Terakhir, perbarui App.svelte Anda untuk menerima properti locale dan menggunakannya dengan useIntlayer:

<script lang="ts">import type { Locale } from 'intlayer';import { useIntlayer } from 'svelte-intlayer';import Counter from './lib/Counter.svelte';import LocaleSwitcher from './lib/LocaleSwitcher.svelte';export let locale: Locale;$: content = useIntlayer('app', locale);</script><main>  <div class="locale-switcher-container">    <LocaleSwitcher currentLocale={locale} />  </div>  <!-- ... sisa aplikasi Anda ... --></main>

Konfigurasi Routing Server-Side (Opsional)

Secara paralel, 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 mengatur 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, maka akan mengarahkan ulang ke locale default.

Perlu diperhatikan bahwa untuk menggunakan intlayerProxy di produksi, Anda perlu memindahkan paket vite-intlayer dari devDependencies ke dependencies.

import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer, intlayerProxy } from "vite-intlayer";typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer, intlayerProxy } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), intlayer(), intlayerProxy()],});

(Opsional) Langkah 8: Ubah URL saat locale berubah

Untuk memungkinkan pengguna mengganti bahasa dan memperbarui URL sesuai, Anda dapat membuat komponen LocaleSwitcher. Komponen ini akan menggunakan getLocalizedUrl dari intlayer dan push dari svelte-spa-router.

<script lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";import { push } from "svelte-spa-router";export let currentLocale: string | undefined = undefined;// Dapatkan informasi localeconst { locale, availableLocales } = useLocale();// Tangani perubahan localeconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  const currentUrl = window.location.pathname;  const url = getLocalizedUrl( currentUrl, newLocale);  push(url);};</script><div class="locale-switcher">  <select value={currentLocale ?? $locale} onchange={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

Konfigurasi Git

Disarankan untuk mengabaikan file-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.
• Tindakan cepat untuk dengan mudah membuat dan memperbarui terjemahan.

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

Melangkah Lebih Jauh

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