Merge pull request #131 from Baptistemontan/update_doc

Update doc for the incoming `v0.4`
Baptistemontan · Aug 20, 2024 · 6006a26 · 6006a26
2 parents 0200676 + 1c2ae8e
commit 6006a26
Show file tree

Hide file tree

Showing 41 changed files with 303 additions and 751 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/book/src/01_introduction.md b/docs/book/src/01_introduction.md
@@ -6,6 +6,4 @@ This crate is made to simplify Internationalization in a [Leptos](https://crates
 
 This guide does assume you know some basics about `Leptos`, but the majority of the guide is about declaring the translations and how to use them, you can find the `Leptos` book [here](https://leptos-rs.github.io/leptos/).
 
-You can find more detailed docs for each part of the API at [Docs.rs](https://docs.rs/leptos_i18n/latest/leptos_i18n/).
-
 > The source code for the book is available [here](https://github.com/Baptistemontan/leptos_i18n/tree/main/docs/book). PRs for typos or clarification are always welcome.
diff --git a/docs/book/src/02_getting_started.md b/docs/book/src/02_getting_started.md
@@ -8,6 +8,12 @@ Once you have set one up, you can add this crate to your project with
 cargo add leptos_i18n
 ```
 
+Or by adding this line to your `Cargo.toml` under `[dependencies]`:
+
+```toml
+leptos_i18n = "0.4"
+```
+
 ## `actix-web` Backend
 
 When compiling for the backend using `actix-web`, enable the `actix` feature:
@@ -21,8 +27,6 @@ ssr = [
 ]
 ```
 
-You can see an example using `actix-web` [here](https://github.com/Baptistemontan/leptos_i18n/tree/master/examples/hello_world_actix)
-
 ## `axum` Backend
 
 When compiling for the backend using `axum`, enable the `axum` feature:
@@ -36,8 +40,6 @@ ssr = [
 ]
 ```
 
-You can see an example using `axum` [here](https://github.com/Baptistemontan/leptos_i18n/tree/master/examples/hello_world_axum)
-
 ## Hydrate
 
 When compiling for the client, enable the `hydrate` feature:
@@ -51,12 +53,6 @@ hydrate = [
 ]
 ```
 
-There exist 3 examples using hydration:
-
-- [Hello World Actix](https://github.com/Baptistemontan/leptos_i18n/tree/master/examples/hello_world_actix)
-- [Hello World Axum](https://github.com/Baptistemontan/leptos_i18n/tree/master/examples/hello_world_axum)
-- [Using Workspace](https://github.com/Baptistemontan/leptos_i18n/tree/master/examples/workspace)
-
 ## Client Side Rendering
 
 When compiling for the client, enable the `csr` feature:
@@ -68,4 +64,4 @@ When compiling for the client, enable the `csr` feature:
 features = ["csr"]
 ```
 
-You can find an example using CSR [here](https://github.com/Baptistemontan/leptos_i18n/tree/master/examples/csr)
+You can find examples using CSR on the [github repo](https://github.com/Baptistemontan/leptos_i18n/tree/master/examples/csr)
diff --git a/docs/book/src/06_features.md b/docs/book/src/06_features.md
@@ -18,13 +18,28 @@ This feature must be enabled when building the client in ssr mode
 
 This feature must be enabled when building the client in csr mode
 
+#### `cookie` (Default)
+
+Set a cookie to remember the last chosen locale.
+
+#### `sync`
+
+This feature has no impact on the user.
+This feature allow the crate to use sync data types such as `Mutex` or `OnceLock`.
+Activated when the `actix` or `axum` feature is enabled.
+
+#### `experimental-islands`
+
+This feature is, as it's name says, experimental.
+This make this lib somewhat usable when using `islands` with Leptos.
+
 #### `serde`
 
 This feature implement `Serialize` and `Deserialize` for the `Locale` enum
 
-#### `debug_interpolations`
+#### `interpolate_display`
 
-This features allow the `load_locales!` macro to generate more code for interpolations, allowing better error reporting when keys are missing.
+This feature generate extra code for each interpolation to allow rendering them as a string instead of a `View`.
 
 #### `show_keys_only`
 
@@ -42,14 +57,10 @@ To enable when you use JSON files for your locales
 
 To enable when you use YAML files for your locales
 
-#### `cookie` (Default)
-
-Set a cookie to remember the last chosen locale.
-
 #### `nightly`
 
-- Enable the use of some nightly features, like directly calling the context to get/set the current locale.
-- Allow the `load_locale!` macro to emit better warnings.
+Enable the use of some nightly features, like directly calling the context to get/set the current locale.
+and allow the `load_locale!` macro to emit better warnings.
 
 #### `track_locale_files`
 

diff --git a/docs/book/src/declare/01_key_value.md b/docs/book/src/declare/01_key_value.md
@@ -40,11 +40,9 @@ If a key is present in another locale but not in the default locale, this key wi
 
 You can specify multiple kinds of values:
 
-- String
-- Numbers
-- Boolean
+- Literals (String, Numbers, Boolean)
 - Interpolated String
 - Ranges
 - Plurals
 
-The next chapters of this section will cover them, apart for strings, those are self explanatory.
+The next chapters of this section will cover them, apart for literals, those are self explanatory.
diff --git a/docs/book/src/declare/05_subkeys.md b/docs/book/src/declare/05_subkeys.md
@@ -13,3 +13,8 @@ You can declare subkeys by just giving a map to the key:
   }
 }
 ```
+
+```rust
+t!(i18n, subkeys.subkey_1); // -> "This is subkey_1"
+t!(i18n, subkeys.nested_subkeys.nested_subkey_1) // -> "you can nest subkeys"
+```
diff --git a/docs/book/src/infos/01_locale_resol.md b/docs/book/src/infos/01_locale_resol.md
@@ -10,4 +10,4 @@ Here is the list of detection methods, sorted in priorities:
 1. A locale can be matched base on the [`navigator.languages` API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages) in CSR
 1. As a last resort, the default locale is used.
 
-In SSR it is always the server that resolves what locale to use, the client do not tries to compute a locale when loading, the only locale changes that can happen is by explicitly setting in in the context.
+In SSR it is always the server that resolves what locale to use, the client do not tries to compute a locale when loading, the only locale changes that can happen is by explicitly setting it in the context.
diff --git a/docs/book/src/setting_up/02_file_structure.md b/docs/book/src/setting_up/02_file_structure.md
@@ -41,7 +41,7 @@ JSON being the default, you can change that by first removing the defaults featu
 [dependencies]
 leptos_i18n = {
     default-features = false,
-    features = ["yaml_files"] # other default features: ["cookie"]
+    features = ["yaml_files"]
 }
 ```
 

diff --git a/docs/book/src/usage/01_load.md b/docs/book/src/usage/01_load.md
@@ -25,18 +25,13 @@ locales = ["en", "fr"]
 Generate this enum:
 
 ```rust
-#[derive(Copy, Clone, Debug, Hash, PartialEq, Eq)]
+#[derive(Copy, Clone, Debug, Hash, PartialEq, Eq, Default)]
 #[allow(non_camel_case_types)]
 pub enum Locale {
+    #[default]
     en,
     fr
 }
-
-impl Default for Locale {
-    fn default() -> Self {
-        Locale::en
-    }
-}
 ```
 
 ### The `I18nKeys` struct
@@ -61,11 +56,28 @@ It contain an associated constant for each locale, where every field is populate
 }
 ```
 
+This will generate this struct:
+
+````rust
+pub struct I18nKeys {
+  pub hello_world: &'static str,
+}
+
+impl I18nKeys {
+  const en: Self = I18nKeys { hello_world: "Hello World!" };
+  const fr: Self = I18nKeys { hello_world: "Bonjour le Monde!" };
+}
+
 ```rust
 leptos_i18n::load_locales!();
 
 assert_eq!(i18n::I18nKeys::en.hello_world, "Hello World!");
 assert_eq!(i18n::I18nKeys::fr.hello_world, "Bonjour le Monde!");
-```
+````
+
+This way of accessing the values is possible but it's not practical and most importantly not reactive, we will cover the `t!` macro later,
+which let you access the values based on the context:
 
-This way of accessing the values is possible but it's not practical and most importantly not reactive, we will cover in a later section the tool this crate give you to simplify it.
+```rust
+t!(i18n, hello_world)
+```
diff --git a/docs/book/src/usage/02_context.md b/docs/book/src/usage/02_context.md
@@ -57,7 +57,6 @@ pub fn Foo() -> impl IntoView {
 
     create_effect(|_| {
         let locale = i18n.get_locale();
-
         match locale {
             Locale::en => {
                 log!("locale en");

diff --git a/docs/expanded_macros/load_locales.md b/docs/expanded_macros/load_locales.md
@@ -1,4 +1,4 @@
-This document contain what the `load_locales!` macro should expand to based on the given locales files, the only relevant feature flag enabled is `serde`, the relevant _not_ enabled feature flags are `debug_interpolations`, `suppress_key_warnings` and `nightly`.
+This document contain what the `load_locales!` macro should expand to based on the given locales files, the only relevant feature flag enabled is `serde`, the relevant _not_ enabled feature flags are `suppress_key_warnings` and `nightly`.
 
 None of the comments are part of the outputed code, they are here to explain the choices made that lead to this code.
 
@@ -217,7 +217,6 @@ pub mod i18n {
         // The build function is pointless work wise, as it just return itself
         // This code is to gate uncomplete builders,
         // if a key is missing you'll get a `builder function does not exist ...` type of error, instead of the obscure `IntoView is not implemented on super_weird_generics_whatever`. Not a lot better in itself, but from what I've seen the `IntoView` error span the whole `view!` macro, but the build function error span only the `t!` macro, which is a lot more helpfull.
-        // This also allow to generate variants of this function that can serves as better error feedback with the `debug_interpolations` feature.
         #[allow(non_camel_case_types)]
         impl<
             __var_count: Fn() -> u32 + core::clone::Clone + 'static,

diff --git a/examples/csr/counter/Cargo.toml b/examples/csr/counter/Cargo.toml
@@ -8,10 +8,7 @@ edition = "2021"
 [dependencies]
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
-leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
-    "csr",
-] }
+leptos_i18n = { path = "../../../leptos_i18n", features = ["csr"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1" }
 wasm-bindgen = { version = "0.2" }

diff --git a/examples/csr/counter_ranges/Cargo.toml b/examples/csr/counter_ranges/Cargo.toml
@@ -6,10 +6,7 @@ edition = "2021"
 [dependencies]
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
-leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
-    "csr",
-] }
+leptos_i18n = { path = "../../../leptos_i18n", features = ["csr"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1" }
 wasm-bindgen = { version = "0.2" }

diff --git a/examples/csr/interpolation/Cargo.toml b/examples/csr/interpolation/Cargo.toml
@@ -8,10 +8,7 @@ edition = "2021"
 [dependencies]
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
-leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
-    "csr",
-] }
+leptos_i18n = { path = "../../../leptos_i18n", features = ["csr"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1" }
 wasm-bindgen = { version = "0.2" }

diff --git a/examples/csr/namespaces/Cargo.toml b/examples/csr/namespaces/Cargo.toml
@@ -8,10 +8,7 @@ edition = "2021"
 [dependencies]
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
-leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
-    "csr",
-] }
+leptos_i18n = { path = "../../../leptos_i18n", features = ["csr"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1" }
 wasm-bindgen = { version = "0.2" }

diff --git a/examples/csr/routing_csr/Cargo.toml b/examples/csr/routing_csr/Cargo.toml
@@ -8,10 +8,7 @@ edition = "2021"
 [dependencies]
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
-leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
-    "csr",
-] }
+leptos_i18n = { path = "../../../leptos_i18n", features = ["csr"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1" }
 wasm-bindgen = { version = "0.2" }

diff --git a/examples/csr/subcontext/Cargo.toml b/examples/csr/subcontext/Cargo.toml
@@ -8,10 +8,7 @@ edition = "2021"
 [dependencies]
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
-leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
-    "csr",
-] }
+leptos_i18n = { path = "../../../leptos_i18n", features = ["csr"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1" }
 wasm-bindgen = { version = "0.2" }

diff --git a/examples/csr/subkeys/Cargo.toml b/examples/csr/subkeys/Cargo.toml
@@ -8,10 +8,7 @@ edition = "2021"
 [dependencies]
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
-leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
-    "csr",
-] }
+leptos_i18n = { path = "../../../leptos_i18n", features = ["csr"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1" }
 wasm-bindgen = { version = "0.2" }

diff --git a/examples/csr/yaml/Cargo.toml b/examples/csr/yaml/Cargo.toml
@@ -9,7 +9,6 @@ edition = "2021"
 leptos = { version = "0.6", features = ["csr"] }
 leptos_meta = { version = "0.6", features = ["csr"] }
 leptos_i18n = { path = "../../../leptos_i18n", default-features = false, features = [
-    "debug_interpolations",
     "csr",
     "cookie",
     "yaml_files",

diff --git a/examples/ssr/axum_island/Cargo.toml b/examples/ssr/axum_island/Cargo.toml
@@ -16,7 +16,6 @@ leptos_axum = { version = "0.6", optional = true, features = [
     "experimental-islands",
 ] }
 leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
     "track_locale_files",
     "experimental-islands",
 ] }

diff --git a/examples/ssr/hello_world_actix/Cargo.toml b/examples/ssr/hello_world_actix/Cargo.toml
@@ -15,7 +15,6 @@ leptos = "0.6"
 leptos_meta = "0.6"
 leptos_actix = { version = "0.6.0", optional = true }
 leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
     "track_locale_files",
 ] }
 serde = { version = "1", features = ["derive"] }

diff --git a/examples/ssr/hello_world_axum/Cargo.toml b/examples/ssr/hello_world_axum/Cargo.toml
@@ -14,7 +14,6 @@ leptos = "0.6"
 leptos_meta = "0.6"
 leptos_axum = { version = "0.6", optional = true }
 leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
     "track_locale_files",
 ] }
 serde = { version = "1", features = ["derive"] }

diff --git a/examples/ssr/routing_ssr/Cargo.toml b/examples/ssr/routing_ssr/Cargo.toml
@@ -14,7 +14,6 @@ leptos = "0.6"
 leptos_meta = "0.6"
 leptos_axum = { version = "0.6", optional = true }
 leptos_i18n = { path = "../../../leptos_i18n", features = [
-    "debug_interpolations",
     "track_locale_files",
 ] }
 serde = { version = "1", features = ["derive"] }

diff --git a/examples/ssr/workspace/client/Cargo.toml b/examples/ssr/workspace/client/Cargo.toml
@@ -14,10 +14,7 @@ actix-web = { version = "4.4", optional = true, features = ["macros"] }
 leptos = "0.6"
 leptos_meta = "0.6"
 leptos_actix = { version = "0.6", optional = true }
-leptos_i18n = { workspace = true, features = [
-    "debug_interpolations",
-    "track_locale_files",
-] }
+leptos_i18n = { workspace = true, features = ["track_locale_files"] }
 serde = { version = "1", features = ["derive"] }
 console_error_panic_hook = { version = "0.1", optional = true }
 wasm-bindgen = { version = "0.2", optional = true }
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,6 +6,4 @@ This crate is made to simplify Internationalization in a [Leptos](https://crates

		This guide does assume you know some basics about `Leptos`, but the majority of the guide is about declaring the translations and how to use them, you can find the `Leptos` book [here](https://leptos-rs.github.io/leptos/).

		You can find more detailed docs for each part of the API at [Docs.rs](https://docs.rs/leptos_i18n/latest/leptos_i18n/).

		> The source code for the book is available [here](https://github.com/Baptistemontan/leptos_i18n/tree/main/docs/book). PRs for typos or clarification are always welcome.
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,3 +13,8 @@ You can declare subkeys by just giving a map to the key: @@
       }
     }
     ```
+    ```rust
+    t!(i18n, subkeys.subkey_1); // -> "This is subkey_1"
+    t!(i18n, subkeys.nested_subkeys.nested_subkey_1) // -> "you can nest subkeys"
+    ```