svelte-tiny-i18n 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,8 @@
 # svelte-tiny-i18n
 
-[](https://www.google.com/search?q=https://www.npmjs.com/package/svelte-tiny-i18n)
-[](https://opensource.org/licenses/MIT)
-[](https://www.google.com/search?q=https://bundlephobia.com/package/svelte-tiny-i18n)
+[![NPM Version](https://img.shields.io/npm/v/svelte-tiny-i18n)](https://www.npmjs.com/package/svelte-tiny-i18n)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/svelte-tiny-i18n)](https://bundlephobia.com/package/svelte-tiny-i18n)
 
 ( English | [繁體中文](./README.zh_tw.md) )
 
@@ -14,12 +14,26 @@ This library is "headless," meaning it only provides the core logic and Svelte s
 
 `svelte-tiny-i18n` is for developers who value **extreme lightweightness, zero dependencies, and zero build-time configuration**, while still enjoying a **native Svelte store experience and instant TypeScript inference**.
 
-Its key advantage is: **You define your translations in your `i18n.ts` config file, and TypeScript _immediately_ gives you type-safety and autocompletion** for both `$t('...')` keys and `locale.set('...')` language codes, all without running a code generator.
+Its key advantage: **Zero-config type safety**. You define your supported locales (e.g., `['en', 'es']`) in a single config file, and TypeScript immediately provides type-checking and autocompletion for your `setLocale` function (e.g., `setLocale('es')` is valid, `setLocale('fr')` is an error) — all without running a code generator.
 
 This makes it the ideal choice for small-to-medium projects and Svelte purists.
 
 ### Example: Minimal SvelteKit Integration
 
+Assuming a project structure like this:
+
+```tree
+/src
+├── /lib
+│   └── i18n.ts         <- 1. Config File
+└── /routes
+    └── /[lang]
+        ├── +layout.ts  <- 2. SvelteKit Integration
+        ├── +page.svelte  <- 3. Usage
+        └── /about
+            └── +page.svelte
+```
+
 1. **`src/lib/i18n.ts`** (Config File)
 
     ```ts
@@ -40,39 +54,31 @@ This makes it the ideal choice for small-to-medium projects and Svelte purists.
     export type SupportedLocale = inferSupportedLocale<typeof i18n>;
     ```
 
-2. **`src/routes/+layout.ts`** (SvelteKit Integration)
+2. **`src/routes/[lang]/+layout.ts`** (SvelteKit Integration)
 
     ```ts
     import { i18n } from '$lib/i18n';
     import type { LayoutLoad } from './$types';
 
     export const load: LayoutLoad = ({ params }) => {
-        // 'lang' comes from your route, e.g., /[[lang]]/
+        // 'lang' comes from your route, e.g., /[lang]/
         i18n.setLocale(params.lang);
         return {};
     };
     ```
 
-3. **`src/routes/+page.svelte`** (Usage)
+3. **`src/routes/[lang]/+page.svelte`** (Usage)
 
     ```svelte
     <script lang="ts">
         import { i18n } from '$lib/i18n';
-        const { t, locale } = i18n;
+        const { t, setLocale } = i18n;
     </script>
 
     <h1>{$t('hello')}</h1>
-    <button on:click={() => locale.set('es')}>Español</button>
+    <button on:click={() => setLocale('es')}>Español</button>
     ```
 
-## Core Concepts
-
-1. **Type-safe by default**: Automatically infers language codes and translation keys from your config.
-2. **Svelte Native**: Built using Svelte stores (`writable` and `derived`). Integration feels fluid and natural.
-3. **SvelteKit Ready**: Correctly handles language detection and initialization in both SSR (Server-Side Rendering) and CSR (Client-Side Rendering).
-4. **Dynamic & Async Loading**: Easily load translations on demand (e.g., for specific pages) using `extendTranslations`.
-5. **Lightweight**: Minimal dependencies and a tiny bundle size.
-
 ## Installation
 
 ```bash
@@ -147,21 +153,14 @@ export type PartialTranslationEntry = inferPartialTranslationEntry<typeof i18n>;
 
 ### 2. Use in Svelte Components
 
-Use the derived store `$t` to get translations, and the `locale` store to read or set the language.
+Use the derived store `$t` to get translations, and the `locale` store to read or `setLocale` to set the language.
 
 ```svelte
 <script lang="ts">
     import { i18n } from '$lib/i18n';
-    import type { SupportedLocale } from '$lib/i18n';
 
     // Destructure the stores and functions
-    const { t, locale } = i18n;
-
-    function setLang(lang: SupportedLocale) {
-        // Just set the store's value.
-        // The '$t' store will update automatically.
-        locale.set(lang);
-    }
+    const { t, locale, setLocale } = i18n;
 </script>
 
 <h1>{$t('hello', { name: 'World' })}</h1>
@@ -169,9 +168,9 @@ Use the derived store `$t` to get translations, and the `locale` store to read o
 <nav>
     <p>Current language: {$locale}</p>
 
-    <button on:click={() => setLang('en')}>English</button>
-    <button on:click={() => setLang('es')}>Español</button>
-    <button on:click={() => setLang('zh-TW')}>繁體中文</button>
+    <button on:click={() => setLocale('en')}>English</button>
+    <button on:click={() => setLocale('es')}>Español</button>
+    <button on:click={() => setLocale('zh-TW')}>繁體中文</button>
 </nav>
 
 <p>{$t('a.missing.key')}</p>
@@ -188,7 +187,7 @@ import type { LayoutLoad } from './$types';
 
 // This load function runs on both SSR and CSR
 export const load: LayoutLoad = ({ params }) => {
-    // 'lang' must match your route parameter, e.g., /[[lang]]/
+    // 'lang' must match your route parameter, e.g., /[lang]/
     const { lang } = params;
 
     // The setLocale function validates the lang
@@ -200,7 +199,7 @@ export const load: LayoutLoad = ({ params }) => {
 };
 ```
 
-**Note:** Your SvelteKit route structure must be similar to `/src/routes/[[lang]]/...` for `params.lang` to be available.
+**Note:** Your SvelteKit route structure must be similar to `/src/routes/[lang]/...` for `params.lang` to be available.
 
 ## Advanced Usage
 
@@ -251,17 +250,17 @@ The new translations are now merged into the store and available via the `$t` fu
 
 `svelte-tiny-i18n` is designed to be the "sweet spot" for Svelte developers who need a simple, fast, and type-safe solution without the overhead of larger libraries.
 
-- **Zero-Config Type Safety**: Get full type-safety for your language codes and translation entries _without_ a build step, code generator, or complex setup. Type-safety is achieved instantly via TypeScript inference from your single configuration object.
-- **Extremely Lightweight**: This library is "tiny" (likely ~1-2kb gzipped). It has **zero dependencies** and does not bundle a heavy ICU message parser, making your app faster.
+- **Zero-Config Type Safety**: Get full type-safety for your language codes _without_ a build step, code generator, or complex setup. Type-safety is achieved instantly via TypeScript inference from your single configuration object.
+- **Extremely Lightweight**: This library is "tiny" (likely <1kb gzipped). It has **zero dependencies** and does not bundle a heavy ICU message parser, making your app faster.
 - **Svelte Native**: Built purely with Svelte stores (`writable` and `derived`), it integrates seamlessly into the Svelte reactivity model.
 - **Simple but Powerful**: Provides all the essential features: SSR/CSR support for SvelteKit, dynamic/async translation loading (`extendTranslations`), and simple variable substitution.
-- **"Headless" by Design**: It provides only the core logic, giving you full control over your UI and integration.
+- **"Headless" by Design**: It provides only the core logic, giving you full control over your UI and integration. (This also means you are responsible for updating the `<html>` `lang` attribute; see the [FAQ for a recipe](#q-how-do-i-dynamically-update-the-html-lang-attribute-or-handle-rtl-right-to-left-languages).)
 
 ## Comparison with Other Libraries
 
 | Dimension            | `svelte-tiny-i18n` (This)                                                    | `typesafe-i18n`                                                         | `svelte-i18n`                                              |
 | :------------------- | :--------------------------------------------------------------------------- | :---------------------------------------------------------------------- | :--------------------------------------------------------- |
-| **Bundle Size**      | **Tiny (~1-2kb)**                                                            | **Tiny (~1kb)**                                                         | **Medium (~15kb+)**                                        |
+| **Bundle Size**      | **Tiny (<1kb)**                                                              | **Tiny (~1kb)**                                                         | **Medium (~15kb+)**                                        |
 | **Core Mechanism**   | Zero-dependency Svelte Stores + Simple String Replace                        | **Build-time Generator**                                                | **Runtime ICU Parser**                                     |
 | **Type Safety**      | **High (Instant Inference)**                                                 | **Very High (Code-Gen)**                                                | Medium (Manual setup)                                      |
 | **Setup Complexity** | **Very Low** (Single config file)                                            | Medium (Requires generator setup)                                       | Low (Install and use)                                      |
@@ -298,7 +297,7 @@ When you call `createI18nStore`, you get an object with:
 - `t`: (Read-only derived store) The translation function.
     - `$t('key')`
     - `$t('key', { placeholder: 'value' })`
-- `locale`: (Writable store) The currently active language code (e.g., `'en'`). You can `set` or `update` this store.
+- `locale`: (Readable store) The currently active language code (e.g., `en`). This store is readable; to update it, use the `setLocale()` function.
 - `setLocale(lang: string | null | undefined)`: A function to safely set the initial language, typically called from the root `+layout.ts`.
     - If `lang` is a supported language, it sets the `locale` store.
     - If `lang` is invalid (or `null`/`undefined`), it's ignored, and the `locale` store **keeps its current value**.
@@ -330,13 +329,48 @@ import type { SupportedLocale } from '$lib/i18n';
 
 // The 'lang' variable is now type-checked
 function setLanguage(lang: SupportedLocale) {
-    i18n.locale.set(lang);
+    i18n.setLocale(lang);
 }
 
 setLanguage('en'); // OK
 setLanguage('fr'); // TypeScript Error
 ```
 
+## FAQ / Recipes
+
+### Q: How do I use this in a Svelte (Vite) project _without_ SvelteKit?
+
+A: It's even simpler. You don't need the `+layout.ts` file or the `i18n.setLocale()` step.
+
+The store will automatically initialize its language in the browser by checking `localStorage` and `navigator.language`. You can change the language at any time by simply calling `i18n.setLocale('new_lang')` in your components.
+
+### Q: How do I dynamically update the `<html>` `lang` attribute or handle RTL (Right-to-Left) languages?
+
+A: This library is "headless," so it doesn't modify the DOM for you. You can easily manage this yourself by subscribing to the `locale` store in your root layout component (e.g., `+layout.svelte` for SvelteKit or `App.svelte` for Svelte/Vite).
+
+Here is an example for a SvelteKit project that sets both the `lang` and `dir` attributes:
+
+```svelte
+<script lang="ts">
+    import { i18n } from '$lib/i18n';
+    const { locale } = i18n;
+
+    // Define which of your supported locales are RTL
+    // (e.g., Arabic 'ar', Hebrew 'he')
+    const rtlLocales: string[] = ['ar', 'he'];
+
+    $: if (typeof document !== 'undefined') {
+        const direction = rtlLocales.includes($locale) ? 'rtl' : 'ltr';
+
+        // Dynamically set attributes on <html>
+        document.documentElement.lang = $locale;
+        document.documentElement.dir = direction;
+    }
+</script>
+
+<slot />
+```
+
 ## License
 
 [MIT](https://opensource.org/licenses/MIT)

package/README.zh_tw.md

@@ -1,8 +1,8 @@
 # svelte-tiny-i18n
 
-[](https://www.google.com/search?q=https://www.npmjs.com/package/svelte-tiny-i18n)
-[](https://opensource.org/licenses/MIT)
-[](https://www.google.com/search?q=https://bundlephobia.com/package/svelte-tiny-i18n)
+[![NPM Version](https://img.shields.io/npm/v/svelte-tiny-i18n)](https://www.npmjs.com/package/svelte-tiny-i18n)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/svelte-tiny-i18n)](https://bundlephobia.com/package/svelte-tiny-i18n)
 
 ( [English](README.md) | 繁體中文 )
 
@@ -14,12 +14,26 @@
 
 `svelte-tiny-i18n` 是為那些**追求極致輕量、零依賴、零建構設定**，同時又**享受 Svelte 原生 Store 體驗和 TypeScript 即時型別推斷**的開發者設計的。
 
-它的核心優勢是：**您在 `i18n.ts` 設定檔中定義翻譯，TypeScript 立刻就能為您提供 `$t('...')` 的 key 自動完成和 `locale.set('...')` 的語言代碼檢查，完全不需執行任何程式碼產生器。**
+它的核心優勢是：**零設定的型別安全**。您只需在 `i18n.ts` 設定檔中定義支援的語言（例如 `['en', 'es']`），TypeScript 立刻就能為您的 `setLocale` 函式提供即時的型別檢查與自動補全（例如 `setLocale('es')` 合法，`setLocale('fr')` 會報錯）—— 完全不需執行任何程式碼產生器。
 
 這使它成為中小型專案、或Svelte生態愛好者的理想選擇。
 
 ### 範例：最精簡的 SvelteKit 整合
 
+假設專案的目錄結構如下：
+
+```tree
+/src
+├── /lib
+│   └── i18n.ts         <- 1. 設定檔
+└── /routes
+    └── /[lang]
+        ├── +layout.ts  <- 2. SvelteKit 整合
+        ├── +page.svelte  <- 3. 使用
+        └── /about
+            └── +page.svelte
+```
+
 1. **`src/lib/i18n.ts`** (設定檔)
 
     ```ts
@@ -40,39 +54,31 @@
     export type SupportedLocale = inferSupportedLocale<typeof i18n>;
     ```
 
-2. **`src/routes/+layout.ts`** (SvelteKit 整合)
+2. **`src/routes/[lang]/+layout.ts`** (SvelteKit 整合)
 
     ```ts
     import { i18n } from '$lib/i18n';
     import type { LayoutLoad } from './$types';
 
     export const load: LayoutLoad = ({ params }) => {
-        // 'lang' 來自您的路由 e.g. /[[lang]]/
+        // 'lang' 來自您的路由 e.g. /[lang]/
         i18n.setLocale(params.lang);
         return {};
     };
     ```
 
-3. **`src/routes/+page.svelte`** (使用)
+3. **`src/routes/[lang]/+page.svelte`** (使用)
 
     ```svelte
     <script lang="ts">
         import { i18n } from '$lib/i18n';
-        const { t, locale } = i18n;
+        const { t, setLocale } = i18n;
     </script>
 
     <h1>{$t('hello')}</h1>
-    <button on:click={() => locale.set('es')}>Español</button>
+    <button on:click={() => setLocale('es')}>Español</button>
     ```
 
-## 核心理念
-
-1. **預設型別安全**: 從設定檔中自動推斷語言代碼和翻譯鍵。
-2. **Svelte 原生**: 使用 Svelte stores (`writable` 和 `derived`) 構建。與 Svelte 組件的整合感覺流暢自然。
-3. **SvelteKit 就緒**: 正確處理 SSR (伺服器端渲染) 和 CSR (客戶端渲染) 中的語言偵測和初始化。
-4. **動態與非同步載入**: 使用 `extendTranslations` 輕鬆地按需載入翻譯 (例如：載入特定頁面的翻譯)。
-5. **輕量級**: 最少的依賴和極小的檔案體積。
-
 ## 安裝
 
 ```bash
@@ -117,6 +123,7 @@ const i18nConfig = defineI18nConfig({
     localStorageKey: 'my-app-language',
 
     // (可選) 如果找不到翻譯鍵，在控制台顯示警告
+    // 預設為 true
     devLogs: true,
 
     // 定義初始、全域翻譯
@@ -147,21 +154,14 @@ export type PartialTranslationEntry = inferPartialTranslationEntry<typeof i18n>;
 
 ### 2. 在 Svelte 組件中使用
 
-使用衍生的 store `$t` 來獲取翻譯，並使用 `locale` store 來讀取或設定語言。
+使用衍生的 store `$t` 來獲取翻譯，並使用 `locale` 來讀取、`setLocale` store 來設定語言。
 
 ```svelte
 <script lang="ts">
     import { i18n } from '$lib/i18n';
-    import type { SupportedLocale } from '$lib/i18n';
 
     // 解構 stores 和函式
-    const { t, locale } = i18n;
-
-    function setLang(lang: SupportedLocale) {
-        // 只需設定 store 的值。
-        // '$t' store 將會自動更新。
-        locale.set(lang);
-    }
+    const { t, locale, setLocale } = i18n;
 </script>
 
 <h1>{$t('hello', { name: 'World' })}</h1>
@@ -169,9 +169,9 @@ export type PartialTranslationEntry = inferPartialTranslationEntry<typeof i18n>;
 <nav>
     <p>目前語言: {$locale}</p>
 
-    <button on:click={() => setLang('en')}>English</button>
-    <button on:click={() => setLang('es')}>Español</button>
-    <button on:click={() => setLang('zh-TW')}>繁體中文</button>
+    <button on:click={() => setLocale('en')}>English</button>
+    <button on:click={() => setLocale('es')}>Español</button>
+    <button on:click={() => setLocale('zh-TW')}>繁體中文</button>
 </nav>
 
 <p>{$t('a.missing.key')}</p>
@@ -188,7 +188,7 @@ import type { LayoutLoad } from './$types';
 
 // 這個 load 函式會在 SSR 和 CSR 上都運行
 export const load: LayoutLoad = ({ params }) => {
-    // 'lang' 必須匹配路由參數，例如 /[[lang]]/
+    // 'lang' 必須匹配路由參數，例如 /[lang]/
     const { lang } = params;
 
     // setLocale 函式會驗證語言
@@ -200,7 +200,7 @@ export const load: LayoutLoad = ({ params }) => {
 };
 ```
 
-**注意：** 您的 SvelteKit 路由結構必須類似 `/src/routes/[[lang]]/...` 才能使 `params.lang` 可用。
+**注意：** 您的 SvelteKit 路由結構必須類似 `/src/routes/[lang]/...` 才能使 `params.lang` 可用。
 
 ## 進階用法
 
@@ -251,21 +251,21 @@ export const load: LayoutLoad = ({ params }) => {
 
 `svelte-tiny-i18n` 旨在為 Svelte 開發者提供一個「最佳平衡點」—— 一個簡單、快速且型別安全的解決方案，而無需大型函式庫的額外開銷。
 
-- **零設定的型別安全 (Zero-Config Type Safety)**: 您**不需**任何建構步驟 (build step)、程式碼產生器或複雜設定，就能立即獲得對語言代碼和翻譯條目的完整型別安全。型別安全是透過 TypeScript 對單一設定檔的自動推斷 (inference) 來實現的。
-- **極致輕量 (Extremely Lightweight)**: 這個函式庫非常「微小」（gzipped 後約 1-2kb）。它**沒有任何外部依賴**，也不包含沉重的 ICU 訊息解析器 (message parser)，使您的應用程式啟動更快。
+- **零設定的型別安全 (Zero-Config Type Safety)**: 您**不需**任何建構步驟 (build step)、程式碼產生器或複雜設定，就能立即獲得對語言代碼的完整型別安全。型別安全是透過 TypeScript 對單一設定檔的自動推斷 (inference) 來實現的。
+- **極致輕量 (Extremely Lightweight)**: 這個函式庫非常「微小」（gzipped 後約 <1kb）。它**沒有任何外部依賴**，也不包含沉重的 ICU 訊息解析器 (message parser)，使您的應用程式啟動更快。
 - **Svelte 原生 (Svelte Native)**: 完全基於 Svelte stores (`writable` 和 `derived`) 構建，使其無縫融入 Svelte 的響應式模型。
 - **簡單而強大 (Simple but Powerful)**: 提供了所有基本功能：支援 SvelteKit 的 SSR/CSR、動態/非同步翻譯載入 (`extendTranslations`)，以及簡單的變數替換。
-- **Headless 設計**: 函式庫只提供核心邏輯，讓您對 UI 整合擁有完全的控制權。
+- **Headless 設計**: 函式庫只提供核心邏輯，讓您對 UI 整合擁有完全的控制權。(這也代表您需要自行更新 `<html>` 上的 `lang` 屬性。請參閱 [FAQ 中的範例](#q-如何動態更新-html-上的-lang-屬性或處理-rtl-由右至左-語言)。)
 
 ## 與其他函式庫比較
 
 | 維度           | `svelte-tiny-i18n` (本專案)                             | `typesafe-i18n`                                   | `svelte-i18n`                                    |
 | :------------- | :------------------------------------------------------ | :------------------------------------------------ | :----------------------------------------------- |
-| **檔案大小**   | **極小 (~1-2kb)**                                       | **極小 (~1kb)**                                   | **中等 (~15kb+)**                                |
+| **檔案大小**   | **極小 (<1kb)**                                         | **極小 (~1kb)**                                   | **中等 (~15kb+)**                                |
 | **核心機制**   | 零依賴的 Svelte Stores + 簡單字串替換                   | **建構期 (Build-time) 產生器**                    | **執行期 (Runtime) ICU 解析器**                  |
 | **型別安全**   | **高 (即時推斷)**                                       | **極高 (程式碼產生)**                             | 中 (需手動定義)                                  |
 | **設定複雜度** | **非常低** (單一設定檔)                                 | 中 (需設定並執行產生器)                           | 低 (安裝即用)                                    |
-| **進階格式化** | 僅支援 `{$t('k', {v: '1'})}` 變數替換                   | 支援 (複數、日期、數字格式化)                     | **支援 (完整 ICU 語法)**                         |
+| **進階格式化** | 僅支援 `{var}` 變數替換                                 | 支援 (複數、日期、數字格式化)                     | **支援 (完整 ICU 語法)**                         |
 | **主要取捨**   | 捨棄 ICU 功能，換取**極致輕量**與**零設定的型別安全**。 | 需額外建構步驟，換取**最強的型別安全** (含參數)。 | 需載入 runtime 解析器，換取**最強的 ICU 功能**。 |
 
 ### 設計理念比較
@@ -298,7 +298,7 @@ export const load: LayoutLoad = ({ params }) => {
 - `t`: (唯讀的 derived store) 翻譯函式。
     - `$t('key')`
     - `$t('key', { placeholder: 'value' })`
-- `locale`: (Writable store) 當前啟用的語言代碼 (例如 `'en'`)。您可以 `set` 或 `update` 這個 store。
+- `locale`: (Readable store) 當前啟用的語言代碼 (例如 `en`)。此 store 是唯讀的；若要更新它，請使用 `setLocale()` 函式。
 - `setLocale(lang: string | null | undefined)`: 一個用於安全設定初始語言的函式，通常在根 `+layout.ts` 中呼叫。
     - 如果 `lang` 是支援的語言，它將設定 `locale` store。
     - 如果 `lang` 是無效的 (或 `null`/`undefined`)，它將被忽略，`locale` store 會**保持其目前的值**。
@@ -330,13 +330,48 @@ import type { SupportedLocale } from '$lib/i18n';
 
 // 'lang' 變數現在受到型別檢查
 function setLanguage(lang: SupportedLocale) {
-    i18n.locale.set(lang);
+    i18n.setLocale(lang);
 }
 
 setLanguage('en'); // OK
 setLanguage('fr'); // TypeScript 錯誤
 ```
 
+## FAQ
+
+### Q: 如何在**不使用 SvelteKit** 的 Svelte (Vite) 專案中使用？
+
+A: 這樣更簡單。您不需要 `+layout.ts` 和 `i18n.setLocale()` 步驟。
+
+Store 在瀏覽器環境中會自動透過 `localStorage` 或 `navigator.language` 來偵測並初始化語言。您可以在組件中隨時呼叫 `i18n.setLocale('new_lang')` 來切換語言。
+
+### Q: 如何動態更新 `<html>` 上的 `lang` 屬性，或處理 RTL (由右至左) 語言？
+
+A: 本函式庫是「Headless」設計，代表它不會主動操作 DOM。您可以輕鬆地在根佈局組件 (SvelteKit 的 `+layout.svelte` 或 Svelte/Vite 的 `App.svelte`) 中訂閱 `locale` store 來自行管理。
+
+這是一個 SvelteKit 專案的範例，它會同時設定 `lang` 和 `dir` 屬性：
+
+```svelte
+<script lang="ts">
+    import { i18n } from '$lib/i18n';
+    const { locale } = i18n;
+
+    // 定義您支援的語言中有哪些是 RTL
+    // (例如阿拉伯語 'ar', 希伯來語 'he')
+    const rtlLocales: string[] = ['ar', 'he'];
+
+    $: if (typeof document !== 'undefined') {
+        const direction = rtlLocales.includes($locale) ? 'rtl' : 'ltr';
+
+        // 動態設定 <html> 上的屬性
+        document.documentElement.lang = $locale;
+        document.documentElement.dir = direction;
+    }
+</script>
+
+<slot />
+```
+
 ## 授權 (License)
 
 [MIT](https://opensource.org/licenses/MIT)

package/dist/svelte-tiny-i18n.cjs

@@ -186,12 +186,12 @@ function createI18nStore(config) {
      */
     localStorageKey,
     /**
-     * A writable Svelte store holding the current language code.
+     * A readable Svelte store holding the current language code.
      * (e.g., 'en')
      *
      * ---
      *
-     * 一個 Svelte Writable store，儲存當前的語言代碼。
+     * 一個 Svelte Readable store，儲存當前的語言代碼。
      * (例如: 'en')
      */
     locale,

package/dist/svelte-tiny-i18n.d.cts

@@ -1,5 +1,13 @@
-import * as svelte_store from 'svelte/store';
-import { Writable } from 'svelte/store';
+import { Readable } from 'svelte/store';
+
+/**
+ * @license MIT
+ * svelte-tiny-i18n
+ * Copyright (c) 2025 Shiritai (Yang Tzu-Ching)
+ *
+ * A tiny, type-safe i18n library for Svelte and SvelteKit.
+ * https://github.com/Shiritai/svelte-tiny-i18n
+ */
 
 /**
  * Interface for the i18n configuration object.
@@ -98,12 +106,11 @@ type PartialTranslationEntryMap<Locales extends string> = {
  * import { i18n } from '$lib/i18n'; // Import the instance from step 1
  *
  * // Destructure the stores and functions
- * const { t, locale } = i18n;
+ * const { t, locale, setLocale } = i18n;
  *
  * function changeLang() {
- *     // You can 'set' the store value directly
  *     const nextLang = $locale === 'en' ? 'es' : 'en';
- *     locale.set(nextLang);
+ *     setLocale(nextLang);
  * }
  * </script>
  *
@@ -151,12 +158,11 @@ type PartialTranslationEntryMap<Locales extends string> = {
  * import { i18n } from '$lib/i18n'; // 導入步驟 1 建立的實例
  *
  * // 解構 Svelte stores 和函式
- * const { t, locale } = i18n;
+ * const { t, locale, setLocale } = i18n;
  *
  * function changeLang() {
- * 	// 你可以直接 'set' store 的值
  * 	const nextLang = $locale === 'en' ? 'es' : 'en';
- * 	locale.set(nextLang);
+ * 	setLocale(nextLang);
  * }
  * </script>
  *
@@ -195,15 +201,15 @@ declare function createI18nStore<const Locales extends readonly string[]>(config
      */
     localStorageKey: string;
     /**
-     * A writable Svelte store holding the current language code.
+     * A readable Svelte store holding the current language code.
      * (e.g., 'en')
      *
      * ---
      *
-     * 一個 Svelte Writable store，儲存當前的語言代碼。
+     * 一個 Svelte Readable store，儲存當前的語言代碼。
      * (例如: 'en')
      */
-    locale: Writable<Locales[number]>;
+    locale: Readable<Locales[number]>;
     /**
      * The translation function.
      *
@@ -225,7 +231,7 @@ declare function createI18nStore<const Locales extends readonly string[]>(config
      * ## 返回值
      * 翻譯後的字串。如果找不到，將回傳 key 本身以方便除錯。
      */
-    t: svelte_store.Readable<(key: string, replacements?: Record<string, string | number>) => string>;
+    t: Readable<(key: string, replacements?: Record<string, string | number>) => string>;
     /**
      * Initializes or updates the language, typically called from a root layout.
      *
@@ -397,7 +403,7 @@ type AnyI18nStore = {
  * function setLanguage(lang: SupportedLocale) {
  *     // The 'lang' variable is now type-checked
  *     // (e.g., only 'en' | 'es' are allowed)
- *     i18n.locale.set(lang);
+ *     i18n.setLocale(lang);
  * }
  *
  * setLanguage('en'); // OK
@@ -419,7 +425,7 @@ type AnyI18nStore = {
  * function setLanguage(lang: SupportedLocale) {
  *     // lang 變數現在會被 TypeScript 檢查
  *     // (例如: 只接受 'en' | 'es')
- *     i18n.locale.set(lang);
+ *     i18n.setLocale(lang);
  * }
  *
  * setLanguage('en'); // OK

package/dist/svelte-tiny-i18n.d.ts

@@ -1,5 +1,13 @@
-import * as svelte_store from 'svelte/store';
-import { Writable } from 'svelte/store';
+import { Readable } from 'svelte/store';
+
+/**
+ * @license MIT
+ * svelte-tiny-i18n
+ * Copyright (c) 2025 Shiritai (Yang Tzu-Ching)
+ *
+ * A tiny, type-safe i18n library for Svelte and SvelteKit.
+ * https://github.com/Shiritai/svelte-tiny-i18n
+ */
 
 /**
  * Interface for the i18n configuration object.
@@ -98,12 +106,11 @@ type PartialTranslationEntryMap<Locales extends string> = {
  * import { i18n } from '$lib/i18n'; // Import the instance from step 1
  *
  * // Destructure the stores and functions
- * const { t, locale } = i18n;
+ * const { t, locale, setLocale } = i18n;
  *
  * function changeLang() {
- *     // You can 'set' the store value directly
  *     const nextLang = $locale === 'en' ? 'es' : 'en';
- *     locale.set(nextLang);
+ *     setLocale(nextLang);
  * }
  * </script>
  *
@@ -151,12 +158,11 @@ type PartialTranslationEntryMap<Locales extends string> = {
  * import { i18n } from '$lib/i18n'; // 導入步驟 1 建立的實例
  *
  * // 解構 Svelte stores 和函式
- * const { t, locale } = i18n;
+ * const { t, locale, setLocale } = i18n;
  *
  * function changeLang() {
- * 	// 你可以直接 'set' store 的值
  * 	const nextLang = $locale === 'en' ? 'es' : 'en';
- * 	locale.set(nextLang);
+ * 	setLocale(nextLang);
  * }
  * </script>
  *
@@ -195,15 +201,15 @@ declare function createI18nStore<const Locales extends readonly string[]>(config
      */
     localStorageKey: string;
     /**
-     * A writable Svelte store holding the current language code.
+     * A readable Svelte store holding the current language code.
      * (e.g., 'en')
      *
      * ---
      *
-     * 一個 Svelte Writable store，儲存當前的語言代碼。
+     * 一個 Svelte Readable store，儲存當前的語言代碼。
      * (例如: 'en')
      */
-    locale: Writable<Locales[number]>;
+    locale: Readable<Locales[number]>;
     /**
      * The translation function.
      *
@@ -225,7 +231,7 @@ declare function createI18nStore<const Locales extends readonly string[]>(config
      * ## 返回值
      * 翻譯後的字串。如果找不到，將回傳 key 本身以方便除錯。
      */
-    t: svelte_store.Readable<(key: string, replacements?: Record<string, string | number>) => string>;
+    t: Readable<(key: string, replacements?: Record<string, string | number>) => string>;
     /**
      * Initializes or updates the language, typically called from a root layout.
      *
@@ -397,7 +403,7 @@ type AnyI18nStore = {
  * function setLanguage(lang: SupportedLocale) {
  *     // The 'lang' variable is now type-checked
  *     // (e.g., only 'en' | 'es' are allowed)
- *     i18n.locale.set(lang);
+ *     i18n.setLocale(lang);
  * }
  *
  * setLanguage('en'); // OK
@@ -419,7 +425,7 @@ type AnyI18nStore = {
  * function setLanguage(lang: SupportedLocale) {
  *     // lang 變數現在會被 TypeScript 檢查
  *     // (例如: 只接受 'en' | 'es')
- *     i18n.locale.set(lang);
+ *     i18n.setLocale(lang);
  * }
  *
  * setLanguage('en'); // OK

package/dist/svelte-tiny-i18n.js

@@ -161,12 +161,12 @@ function createI18nStore(config) {
      */
     localStorageKey,
     /**
-     * A writable Svelte store holding the current language code.
+     * A readable Svelte store holding the current language code.
      * (e.g., 'en')
      *
      * ---
      *
-     * 一個 Svelte Writable store，儲存當前的語言代碼。
+     * 一個 Svelte Readable store，儲存當前的語言代碼。
      * (例如: 'en')
      */
     locale,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-tiny-i18n",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A lightweight, type-safe, and reactive i18n library for Svelte and SvelteKit.",
   "author": "Shiritai",
   "license": "MIT",
@@ -39,11 +39,11 @@
     "dist"
   ],
   "peerDependencies": {
-    "svelte": "^3.30.0"
+    "svelte": "^3.30.0 || ^4.0.0 || ^5.0.0"
   },
   "devDependencies": {
     "@eslint/compat": "^1.2.5",
-    "@types/node": "^22",
+    "@types/node": "^24",
     "eslint": "^9.22.0",
     "eslint-config-prettier": "^10.0.1",
     "jiti": "^2.6.1",
@@ -53,7 +53,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.20.0",
-    "vitest": "^1.0.0"
+    "vitest": "^4.0.0"
   },
   "scripts": {
     "test": "vitest run",