@intlayer/docs 7.1.9 → 7.2.2

package/docs/id/intlayer_with_vite+svelte.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-04-18
-updatedAt: 2025-06-29
+updatedAt: 2025-11-19
 title: Cara menerjemahkan aplikasi Vite dan Svelte Anda – panduan i18n 2025
 description: Temukan cara membuat situs web Vite dan Svelte Anda menjadi multibahasa. Ikuti dokumentasi untuk melakukan internasionalisasi (i18n) dan menerjemahkannya.
 keywords:
@@ -14,37 +14,46 @@ slugs:
   - doc
   - environment
   - vite-and-svelte
-# applicationTemplate: https://github.com/aymericzip/intlayer-vite-svelte-template
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-svelte-template
 history:
+  - version: 5.5.11
+    date: 2025-11-19
+    changes: Memperbarui dokumen
   - version: 5.5.10
     date: 2025-06-29
-    changes: Inisialisasi riwayat
+    changes: Memulai riwayat
 ---
 
 # Terjemahkan situs web Vite dan Svelte Anda menggunakan Intlayer | Internasionalisasi (i18n)
 
-> Paket ini sedang dalam pengembangan. Lihat [issue](https://github.com/aymericzip/intlayer/issues/114) untuk informasi lebih lanjut. Tunjukkan minat Anda pada Intlayer untuk Svelte dengan menyukai issue tersebut
-
-<!-- Lihat [Application Template](https://github.com/aymericzip/intlayer-solid-template) di GitHub. -->
-
 ## Daftar Isi
 
 <TOC/>
 
 ## Apa itu Intlayer?
 
-**Intlayer** adalah pustaka internasionalisasi (i18n) sumber terbuka yang inovatif, dirancang untuk mempermudah dukungan multibahasa dalam aplikasi web modern.
+**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.
-- **Memastikan dukungan TypeScript** dengan tipe yang dihasilkan secara otomatis, meningkatkan autocompletion dan deteksi kesalahan.
-- **Manfaatkan fitur canggih**, seperti deteksi dan pergantian locale 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 di Aplikasi Vite dan Svelte
+## Panduan Langkah demi Langkah untuk Mengatur Intlayer dalam Aplikasi Vite dan Svelte
+
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer-vite-react-template?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Cara Menginternasionalisasi aplikasi Anda menggunakan Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+Lihat [Template Aplikasi](https://github.com/aymericzip/intlayer-vite-svelte-template) di GitHub.
 
 ### Langkah 1: Instalasi Dependensi
 
@@ -65,23 +74,26 @@ yarn add intlayer svelte-intlayer
 yarn add vite-intlayer --save-dev
 ```
 
-- **intlayer**
+```bash packageManager="bun"
+bun add intlayer svelte-intlayer
+bun add vite-intlayer --save-dev
+```
 
 - **intlayer**
 
   Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, [deklarasi konten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/dictionary/content_file.md), transpile, dan [perintah CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_cli.md).
 
 - **svelte-intlayer**
-  Paket yang mengintegrasikan Intlayer dengan aplikasi Svelte. Paket ini menyediakan context providers dan hooks untuk internasionalisasi Svelte.
+  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](https://vite.dev/guide/why.html#why-bundle-for-production), serta middleware untuk mendeteksi locale pilihan pengguna, mengelola cookies, dan menangani pengalihan URL.
+- **vite-intlayer**  
+  Termasuk plugin Vite untuk mengintegrasikan Intlayer dengan [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production), 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:
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
@@ -90,7 +102,7 @@ const config: IntlayerConfig = {
       Locales.ENGLISH,
       Locales.FRENCH,
       Locales.SPANISH,
-      // Bahasa lain milik Anda
+      // Locale lain milik Anda
     ],
     defaultLocale: Locales.ENGLISH,
   },
@@ -99,51 +111,13 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Bahasa lain milik Anda
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Bahasa lain milik Anda
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-module.exports = 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/configuration.md).
 
 ### Langkah 3: Integrasikan Intlayer dalam Konfigurasi Vite Anda
 
 Tambahkan plugin intlayer ke dalam konfigurasi Anda.
 
-```typescript fileName="vite.config.ts" codeFormat="typescript"
+```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
 import { intlayer } from "vite-intlayer";
@@ -154,29 +128,7 @@ export default defineConfig({
 });
 ```
 
-```javascript fileName="vite.config.mjs" codeFormat="esm"
-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()],
-});
-```
-
-```javascript fileName="vite.config.cjs" codeFormat="commonjs"
-const { defineConfig } = require("vite");
-const react = require("@vitejs/plugin-react-swc");
-const { intlayer } = require("vite-intlayer");
-
-// https://vitejs.dev/config/
-module.exports = 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.
+> 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
 
@@ -203,6 +155,7 @@ export default appContent;
 import { t } from "intlayer";
 
 /** @type {import('intlayer').Dictionary} */
+// Mendefinisikan konten aplikasi dengan terjemahan untuk beberapa bahasa
 const appContent = {
   key: "app",
   content: {
@@ -221,7 +174,7 @@ export default appContent;
 const { t } = require("intlayer");
 
 /** @type {import('intlayer').Dictionary} */
-// Deklarasi konten aplikasi
+// Mendefinisikan konten aplikasi dengan terjemahan untuk beberapa bahasa
 const appContent = {
   key: "app",
   content: {
@@ -253,37 +206,264 @@ module.exports = appContent;
 }
 ```
 
-> Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama sudah termasuk 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}`).
+> 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/dictionary/content_file.md).
+
+### Langkah 5: Gunakan Intlayer dalam Kode Anda
+
+```svelte fileName="src/App.svelte"
+<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
 
-> Untuk informasi lebih lanjut, lihat [dokumentasi deklarasi konten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/dictionary/content_file.md).
+```svelte fileName="src/App.svelte"
+<script lang="ts">
+import  { getLocaleName } from 'intlayer';
+import { useLocale } from 'svelte-intlayer';
 
-### Langkah 5: Memanfaatkan Intlayer dalam Kode Anda
+// Dapatkan informasi locale dan fungsi setLocale
+const { locale, availableLocales, setLocale } = useLocale();
 
-[akan diselesaikan]
+// Tangani perubahan locale
+const 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 6: Mengubah bahasa konten Anda
+### (Opsional) Langkah 7: Render Markdown
 
-[akan diselesaikan]
+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.
 
-### (Opsional) Langkah 7: Menambahkan Routing yang Dilokalkan ke aplikasi Anda
+> Untuk melihat cara mendeklarasikan konten markdown menggunakan paket `intlayer`, lihat [dokumen markdown](https://github.com/aymericzip/intlayer/tree/main/docs/docs/id/dictionary/markdown.md).
 
-[akan diselesaikan]
+```svelte fileName="src/App.svelte"
+<script>
+  import { setIntlayerMarkdown } from "svelte-intlayer";
 
-### (Opsional) Langkah 8: Mengubah URL saat locale berubah
+  setIntlayerMarkdown((markdown) =>
+   // render konten markdown sebagai string
+   return markdown;
+  );
+</script>
 
-[akan diselesaikan]
+<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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_visual_editor.md).
 
-### (Opsional) Langkah 9: Mengganti Atribut Bahasa dan Arah HTML
+Untuk menyiapkan CMS intlayer, Anda harus mengikuti [dokumentasi CMS intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_CMS.md).
+
+Secara paralel, dalam aplikasi Svelte Anda, Anda harus menambahkan baris berikut di layout, atau di root aplikasi Anda:
+
+```svelte fileName="src/layout.svelte"
+import { useIntlayerEditor } from "svelte-intlayer";
+
+useIntlayerEditor();
+```
 
-[akan diselesaikan]
+### (Opsional) Langkah 7: Tambahkan Routing yang dilokalkan ke aplikasi Anda
 
-### (Opsional) Langkah 10: Membuat Komponen Link yang Dilokalkan
+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.
 
-[akan diselesaikan]
+Pertama, instal `svelte-spa-router`:
+
+```bash packageManager="npm"
+npm install svelte-spa-router
+```
+
+```bash packageManager="pnpm"
+pnpm add svelte-spa-router
+```
+
+```bash packageManager="yarn"
+yarn add svelte-spa-router
+```
+
+```bash packageManager="bun"
+bun add svelte-spa-router
+```
+
+Kemudian, buat file `Router.svelte` untuk mendefinisikan rute Anda:
+
+```svelte fileName="src/Router.svelte"
+<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`:
+
+```typescript fileName="src/main.ts"
+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`:
+
+```svelte fileName="src/App.svelte"
+<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`.
+
+```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";
+
+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()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.mjs" codeFormat="esm"
+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()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const { svelte } = require("@sveltejs/vite-plugin-svelte");
+const { intlayer, intlayerProxy } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+  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`.
+
+```svelte fileName="src/lib/LocaleSwitcher.svelte"
+<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 locale
+const { locale, availableLocales } = useLocale();
+
+// Tangani perubahan locale
+const 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 yang dihasilkan oleh Intlayer. Ini memungkinkan Anda menghindari meng-commit file tersebut ke repositori Git Anda.
+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:
 
@@ -301,16 +481,14 @@ Untuk meningkatkan pengalaman pengembangan Anda dengan Intlayer, Anda dapat meng
 Ekstensi ini menyediakan:
 
 - **Autocompletion** untuk kunci terjemahan.
-- **Deteksi kesalahan secara real-time** untuk terjemahan yang hilang.
+- **Deteksi kesalahan waktu nyata** untuk terjemahan yang hilang.
 - **Pratinjau inline** dari konten yang diterjemahkan.
 - **Tindakan cepat** untuk dengan mudah membuat dan memperbarui terjemahan.
 
-Untuk informasi lebih lanjut tentang cara menggunakan ekstensi ini, lihat [dokumentasi Ekstensi VS Code Intlayer](https://intlayer.org/doc/vs-code-extension).
+Untuk detail lebih lanjut tentang cara menggunakan ekstensi ini, lihat [dokumentasi Ekstensi VS Code Intlayer](https://intlayer.org/doc/vs-code-extension).
 
 ---
 
 ### Melangkah Lebih Jauh
 
 Untuk melangkah lebih jauh, Anda dapat mengimplementasikan [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_visual_editor.md) atau mengeksternalisasi konten Anda menggunakan [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_CMS.md).
-
----