|
| 1 | +# 🧬 I18N RS Dioxus Usage |
| 2 | + |
| 3 | +Adding I18N RS to your project is simple: |
| 4 | + |
| 5 | +1. Make sure your project is set up with **Dioxus**. Refer to the [Dioxus Getting Started Guide](https://dioxuslabs.com/learn/0.6/getting_started) for setup instructions. |
| 6 | + |
| 7 | +1. Add the **i18nrs** library to your dependencies by including it in your `Cargo.toml` file: |
| 8 | + |
| 9 | + ```sh |
| 10 | + cargo add i18nrs --features=dio |
| 11 | + ``` |
| 12 | + |
| 13 | +1. Import the `I18nProvider` component into your Dioxus application and wrap it around your app's main component to provide translations. |
| 14 | + |
| 15 | +## 🛠️ Usage |
| 16 | + |
| 17 | +Follow these steps to integrate i18nrs into your Dioxus application: |
| 18 | + |
| 19 | +### Step 1: Import the Required Components |
| 20 | + |
| 21 | +Import the `I18nProvider` and related types into your Dioxus project: |
| 22 | + |
| 23 | +```rust |
| 24 | +use dioxus::prelude::*; |
| 25 | +use i18nrs::dioxus::I18nProvider; |
| 26 | +use std::collections::HashMap; |
| 27 | +``` |
| 28 | + |
| 29 | +### Step 2: Define Translations |
| 30 | + |
| 31 | +Define your translations in a `HashMap` where keys are language codes (e.g., `en`, `fr`), and values are the translation strings in JSON format: |
| 32 | + |
| 33 | +```rust |
| 34 | +use dioxus::prelude::*; |
| 35 | +use std::collections::HashMap; |
| 36 | + |
| 37 | +fn app() -> Element { |
| 38 | + let translations = HashMap::from([ |
| 39 | + ("en", r#"{"greeting": "Hello", "farewell": "Goodbye"}"#), |
| 40 | + ("fr", r#"{"greeting": "Bonjour", "farewell": "Au revoir"}"#), |
| 41 | + ]); |
| 42 | + |
| 43 | + rsx! {} |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +### Step 3: Wrap Your App with the `I18nProvider` |
| 48 | + |
| 49 | +Wrap your main app component inside the `I18nProvider` to give it access to the internationalization context: |
| 50 | + |
| 51 | +```rust |
| 52 | +use dioxus::prelude::*; |
| 53 | +use i18nrs::dioxus::I18nProvider; |
| 54 | +use i18nrs::StorageType; |
| 55 | +use std::collections::HashMap; |
| 56 | + |
| 57 | +fn app() -> Element { |
| 58 | + let translations = HashMap::from([ |
| 59 | + ("en", r#"{"greeting": "Hello", "farewell": "Goodbye"}"#), |
| 60 | + ("fr", r#"{"greeting": "Bonjour", "farewell": "Au revoir"}"#), |
| 61 | + ]); |
| 62 | + |
| 63 | + rsx! { |
| 64 | + I18nProvider { |
| 65 | + translations: translations, |
| 66 | + default_language: "en".to_string(), |
| 67 | + MainApp {} |
| 68 | + } |
| 69 | + } |
| 70 | +} |
| 71 | + |
| 72 | +#[component] |
| 73 | +fn MainApp() -> Element { |
| 74 | + rsx! { |
| 75 | + h1 { "Welcome to i18nrs Dioxus Example!" } |
| 76 | + } |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +### Step 4: Access Translations via Context |
| 81 | + |
| 82 | +Use the `use_context` hook to access the i18n instance and call translations inside your components: |
| 83 | + |
| 84 | +```rust |
| 85 | +use dioxus::prelude::*; |
| 86 | +use i18nrs::dioxus::I18nContext; |
| 87 | + |
| 88 | +#[component] |
| 89 | +fn MainApp() -> Element { |
| 90 | + let I18nContext { i18n, set_language } = use_context::<I18nContext>(); |
| 91 | + |
| 92 | + let greeting = i18n().t("greeting"); |
| 93 | + |
| 94 | + rsx! { |
| 95 | + div { |
| 96 | + h1 { "{greeting}" } |
| 97 | + button { |
| 98 | + onclick: move |_| set_language.call("fr".to_string()), |
| 99 | + "Switch to French" |
| 100 | + } |
| 101 | + } |
| 102 | + } |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +## 🔧 Props |
| 107 | + |
| 108 | +### `I18nProviderProps` Props |
| 109 | + |
| 110 | +#### Main Props |
| 111 | + |
| 112 | +| Property | Type | Description | Default | |
| 113 | +| ------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------- | |
| 114 | +| `translations` | `HashMap<&'static str, &'static str>` | Mapping of language codes to translation JSON content. Defaults to an empty map. | `{}` | |
| 115 | +| `children` | `Element` | Child components that will have access to the i18n context. | **Required** | |
| 116 | +| `storage_type` | `StorageType` | Type of browser storage for persisting the selected language (`LocalStorage` or `SessionStorage`). | `LocalStorage` | |
| 117 | +| `storage_name` | `String` | Key name in browser storage for saving the selected language. | `"i18nrs"` | |
| 118 | +| `default_language` | `String` | Language to fall back to if none is found in storage. | `"en"` | |
| 119 | + |
| 120 | +#### Behavioral Props |
| 121 | + |
| 122 | +| Property | Type | Description | Default | |
| 123 | +| ---------- | ------------------ | ---------------------------------------------------------------------------------------------- | ------- | |
| 124 | +| `onchange` | `EventHandler<String>` | Callback triggered when the language is changed. Receives the new language code as a `String`. | No-op | |
| 125 | +| `onerror` | `EventHandler<String>` | Callback triggered when an error occurs in the i18n process. Receives the error message. | No-op | |
| 126 | + |
| 127 | +## 💡 Notes |
| 128 | + |
| 129 | +1. **Translation Keys**: Use dot-separated keys to organize translations hierarchically, e.g., `menu.file.open`. Translation files use a JSON format and can include nested keys for better organization. |
| 130 | + |
| 131 | + - Example: |
| 132 | + |
| 133 | + ```json |
| 134 | + { |
| 135 | + "menu": { |
| 136 | + "file": { |
| 137 | + "open": "Open", |
| 138 | + "save": "Save" |
| 139 | + }, |
| 140 | + "edit": "Edit" |
| 141 | + } |
| 142 | + } |
| 143 | + ``` |
| 144 | + |
| 145 | +1. **Language Switching**: Use the `set_language` callback from `I18nContext` to dynamically update the language and persist it using the specified storage type. |
| 146 | + |
| 147 | +1. **Fallback Mechanism**: If a translation is not found for the current language, the default language is used. |
0 commit comments