From: Dietmar Maurer <dietmar@proxmox.com>
Date: Fri, 6 Oct 2023 16:19:02 +0000 (+0200)
Subject: improve gettext docs
X-Git-Url: https://git.proxmox.com/?a=commitdiff_plain;h=3a33cd3667be3b1c8f82a21aa0d8ec4e594eac19;p=ui%2Fproxmox-yew-widget-toolkit.git

improve gettext docs
---

diff --git a/src/gettext_runtime_format.rs b/src/gettext_runtime_format.rs
index b0f7aac..35a90a5 100644
--- a/src/gettext_runtime_format.rs
+++ b/src/gettext_runtime_format.rs
@@ -31,14 +31,14 @@ pub struct FormatArguments<'a> {
 ///
 /// The format string may reference arguments using the following syntax:
 ///
-/// - "{}": use next argument (increments internal position counter).
-/// - "{\<nth\>}": use nth argument, i.e. "{0}" and "{1}".
-/// - "{\<name\>}": use named argument, i.e. "{n}".
+/// - `{}` - use next argument (increments internal position counter).
+/// - `{<nth>}` - use nth argument, i.e. `{0}` and `{1}`.
+/// - `{<name>}` - use named arguments, i.e. `{n}`.
 ///
 /// # Note
 ///
-/// Both [ngettext!] and [npgettext!] get an implicit last argument named 'n', so you can refer to the
-/// counter using "{n}".
+/// Both [ngettext!] and [npgettext!] get an implicit last argument named `n`, so you can refer to the
+/// counter using `{n}`.
 #[macro_export]
 macro_rules! gettext_runtime_format {
     ($format:expr) => {{
diff --git a/src/lib.rs b/src/lib.rs
index d6baa95..991a951 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -177,15 +177,17 @@ pub mod state;
 pub mod touch;
 pub mod widget;
 
+#[doc(hidden)]
 pub mod gettext_runtime_format;
-pub mod tr;
 
-pub mod gettext_wrapper;
+mod gettext_wrapper;
 pub use gettext_wrapper::{
     gettext, gettext_noop, init_i18n, init_i18n_from_blob, init_i18n_from_url, ngettext, npgettext,
     pgettext,
 };
 
+mod tr;
+
 #[doc(hidden)]
 pub mod web_sys_ext;
 
diff --git a/src/tr.rs b/src/tr.rs
index e9e66d3..024e598 100644
--- a/src/tr.rs
+++ b/src/tr.rs
@@ -4,37 +4,103 @@
 use crate::gettext_runtime_format;
 
 #[cfg(doc)]
-use crate::gettext_wrapper::{gettext, pgettext, ngettext, npgettext};
+use crate::{gettext, pgettext, ngettext, npgettext};
 
+/// Macro to translate strings using gettext.
+///
+/// ```
+/// # use pwt::prelude::*;
+/// # fn dummy() -> String {
+/// // Outputs "Hello world!", or a translated version depending on the loaded catalog.
+/// tr!("Hello world!")
+/// # }
+/// ```
+///
+/// The string to translate need to be a string literal, as it has to be extracted by
+/// the `xtr` tool. One can add more argument
+///
+/// ```
+/// # use pwt::prelude::*;
+/// # fn dummy() -> String {
+/// // Outputs "You received 5 messages.", or a translated version.
+/// let message_count = 5;
+/// tr!("You received {} messages", message_count)
+/// # }
+/// ```
+///
+/// The format string may reference arguments using the following syntax:
+///
+/// - `{}` - use next argument (increments internal position counter).
+/// - `{<nth>}` - use nth argument, i.e. `{0}` and `{1}`.
+/// - `{<name>}` - use named arguments, i.e. `{n}`.
+///
+/// Plural are using the `"singular" | "plural" % count` syntax. `{n}` will be replaced
+/// by the count.
+///
+/// ```
+/// # use pwt::prelude::*;
+/// # fn dummy(message_count: usize) -> String {
+/// tr!("You received one message" | "You received {n} messages" % message_count)
+/// # }
+/// ```
+///
+/// Please note that it is still possible to add more arguments
+///
+/// ```
+/// # use pwt::prelude::*;
+/// # fn dummy(number_of_items: usize, folder_name: &str) -> String {
+/// tr!(
+///     "There is one item in folder {}" |
+///     "There are {n} items in folder {}" % number_of_items,
+///     folder_name
+/// )
+/// # }
+/// ```
+///
+/// If you want to use the same string for different pruposes, you may want to use an
+/// disambiguation context, using the `"context" =>` syntax. You simply use this
+/// to give more context to the translators.
+///
+/// ```
+/// # use pwt::prelude::*;
+/// # fn dummy() -> String {
+/// // Outputs "CPU", or a translated version.
+/// tr!("Central Procesing Unit" => "CPU")
+/// # }
+/// ```
+///
+/// To enable the translation, one must first call the [init_i18n](crate::init_i18n).
+/// To translate the strings, one can use the `xtr` utility to extract the string,
+/// and use the other GNU gettext tools to translate them.
 #[macro_export]
 macro_rules! tr {
     ($msgid:tt, $($tail:tt)* ) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::gettext($msgid), $($tail)*)
+        $crate::gettext_runtime_format!($crate::gettext($msgid), $($tail)*)
     };
     ($msgid:tt) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::gettext($msgid))
+        $crate::gettext_runtime_format!($crate::gettext($msgid))
     };
     ($msgctx:tt => $msgid:tt, $($tail:tt)* ) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::pgettext($msgctx, $msgid), $($tail)*)
+        $crate::gettext_runtime_format!($crate::pgettext($msgctx, $msgid), $($tail)*)
     };
     ($msgctx:tt => $msgid:tt) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::pgettext($msgctx, $msgid))
+        $crate::gettext_runtime_format!($crate::pgettext($msgctx, $msgid))
     };
     ($msgid:tt | $plur:tt % $n:expr, $($tail:tt)* ) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::ngettext($msgid, $plur, n), $($tail)*, n=n)
+        $crate::gettext_runtime_format!($crate::ngettext($msgid, $plur, n as u64), $($tail)*, n=n)
     }};
     ($msgid:tt | $plur:tt % $n:expr) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::ngettext($msgid, $plur, n), n=n)
+        $crate::gettext_runtime_format!($crate::ngettext($msgid, $plur, n as u64), n=n)
     }};
     ($msgctx:tt => $msgid:tt | $plur:tt % $n:expr, $($tail:tt)* ) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::npgettext($msgctx, $msgid, $plur, n), $($tail)*, n=n)
+        $crate::gettext_runtime_format!($crate::npgettext($msgctx, $msgid, $plur, n as u64), $($tail)*, n=n)
     }};
     ($msgctx:tt => $msgid:tt | $plur:tt % $n:expr) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::npgettext($msgctzx, $msgid, $plur, n), n=n)
+        $crate::gettext_runtime_format!($crate::npgettext($msgctx, $msgid, $plur, n as u64), n=n)
     }};
 }
 
@@ -42,10 +108,10 @@ macro_rules! tr {
 #[macro_export]
 macro_rules! gettext {
     ($msgid:tt, $($tail:tt)* ) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::gettext($msgid), $($tail)*)
+        $crate::gettext_runtime_format!($crate::gettext($msgid), $($tail)*)
     };
     ($msgid:tt) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::gettext($msgid))
+        $crate::gettext_runtime_format!($crate::gettext($msgid))
     };
 }
 
@@ -56,11 +122,11 @@ macro_rules! gettext {
 macro_rules! ngettext {
     ($msgid:tt , $plur:tt , $n:expr, $($tail:tt)* ) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::ngettext($msgid, $plur, n), $($tail)*, n=n)
+        $crate::gettext_runtime_format!($crate::ngettext($msgid, $plur, n), $($tail)*, n=n)
     }};
     ($msgid:tt , $plur:tt , $n:expr) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::ngettext($msgid, $plur, n), n=n)
+        $crate::gettext_runtime_format!($crate::ngettext($msgid, $plur, n), n=n)
     }};
 }
 
@@ -68,10 +134,10 @@ macro_rules! ngettext {
 #[macro_export]
 macro_rules! pgettext {
     ($msgid:tt, $msgctx:tt,  $($tail:tt)* ) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::pgettext($msgctx, $msgid), $($tail)*)
+        $crate::gettext_runtime_format!($crate::pgettext($msgctx, $msgid), $($tail)*)
     };
     ($msgid:tt, $msgctx:tt) => {
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::pgettext($msgctx, $msgid))
+        $crate::gettext_runtime_format!($crate::pgettext($msgctx, $msgid))
     };
 }
 /// Like [npgettext()], but format arguments using [gettext_runtime_format!].
@@ -81,10 +147,10 @@ macro_rules! pgettext {
 macro_rules! npgettext {
     ($msgctx:tt ,  $msgid:tt , $plur:tt , $n:expr, $($tail:tt)* ) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::npgettext($msgctx, $msgid, $plur, n), $($tail)*, n=n)
+        $crate::gettext_runtime_format!($crate::npgettext($msgctx, $msgid, $plur, n), $($tail)*, n=n)
     }};
     ($msgctx:tt , $msgid:tt , $plur:tt , $n:expr) => {{
         let n = $n;
-        $crate::gettext_runtime_format!($crate::gettext_wrapper::npgettext($msgctzx, $msgid, $plur, n), n=n)
+        $crate::gettext_runtime_format!($crate::npgettext($msgctzx, $msgid, $plur, n), n=n)
     }};
 }