feat(api): add `locale` function, closes #5939 (#5960)

.changes/api-js-os-locale.md

@@ -0,0 +1,5 @@
+---
+'@tauri-apps/api': 'patch'
+---
+
+Add `locale` function in the `os` module to get the system locale.

.changes/api-rs-os-locale.md

@@ -0,0 +1,5 @@
+---
+"tauri": "patch"
+---
+
+Add `tauri::api::os::locale` function to get the system locale.

core/tauri/Cargo.toml

@@ -85,6 +85,7 @@ infer = { version = "0.9", optional = true }
 png = { version = "0.17", optional = true }
 ico = { version = "0.2.0", optional = true }
 encoding_rs = "0.8.31"
+sys-locale = { version = "0.2.3", optional = true }
 
 [target."cfg(any(target_os = \"macos\", windows, target_os = \"linux\", target_os = \"dragonfly\", target_os = \"freebsd\", target_os = \"openbsd\", target_os = \"netbsd\"))".dependencies]
 rfd = { version = "0.10", optional = true, features = [ "gtk3", "common-controls-v6" ] }
@@ -142,6 +143,7 @@ updater = [
 ]
 http-api = [ "attohttpc" ]
 http-multipart = [ "attohttpc/multipart-form", "reqwest/multipart" ]
+os-api = [ "sys-locale" ]
 shell-open-api = [ "open", "regex", "tauri-macros/shell-scope" ]
 fs-extract-api = [ "zip" ]
 reqwest-client = [ "reqwest", "bytes" ]
@@ -213,7 +215,7 @@ global-shortcut-all = [ "global-shortcut" ]
 http-all = [ "http-request" ]
 http-request = [ "http-api" ]
 notification-all = [ "notification", "dialog-ask" ]
-os-all = [ "os_info" ]
+os-all = [ "os_info", "os-api" ]
 path-all = [ ]
 process-all = [ "process-relaunch", "process-exit" ]
 process-exit = [ ]

core/tauri/src/api/mod.rs

@@ -13,6 +13,9 @@ pub mod file;
 #[cfg_attr(doc_cfg, doc(cfg(feature = "http-api")))]
 pub mod http;
 pub mod ipc;
+#[cfg(feature = "os-api")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "os-api")))]
+pub mod os;
 pub mod path;
 pub mod process;
 #[cfg(feature = "shell-open-api")]

core/tauri/src/api/os.rs

@@ -0,0 +1,10 @@
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+//! Types and functions related to operating system operations.
+
+/// Returns `Some(String)` with a `BCP-47` language tag inside. If the locale couldn’t be obtained, `None` is returned instead.
+pub fn locale() -> Option<String> {
+  sys_locale::get_locale()
+}

core/tauri/src/endpoints/operating_system.rs

@@ -20,6 +20,7 @@ pub enum Cmd {
   OsType,
   Arch,
   Tempdir,
+  Locale,
 }
 
 #[cfg(os_all)]
@@ -43,6 +44,10 @@ impl Cmd {
   fn tempdir<R: Runtime>(_context: InvokeContext<R>) -> super::Result<PathBuf> {
     Ok(std::env::temp_dir())
   }
+
+  fn locale<R: Runtime>(_context: InvokeContext<R>) -> super::Result<Option<String>> {
+    Ok(crate::api::os::locale())
+  }
 }
 
 #[cfg(not(os_all))]
@@ -66,6 +71,10 @@ impl Cmd {
   fn tempdir<R: Runtime>(_context: InvokeContext<R>) -> super::Result<PathBuf> {
     Err(crate::Error::ApiNotAllowlisted("os > all".into()).into_anyhow())
   }
+
+  fn locale<R: Runtime>(_context: InvokeContext<R>) -> super::Result<Option<String>> {
+    Err(crate::Error::ApiNotAllowlisted("os > all".into()).into_anyhow())
+  }
 }
 
 #[cfg(os_all)]
@@ -110,4 +119,8 @@ mod tests {
   #[tauri_macros::module_command_test(os_all, "os > all", runtime)]
   #[quickcheck_macros::quickcheck]
   fn tempdir() {}
+
+  #[tauri_macros::module_command_test(os_all, "os > all", runtime)]
+  #[quickcheck_macros::quickcheck]
+  fn locale() {}
 }

core/tauri/src/lib.rs

@@ -25,6 +25,7 @@
 //! - **reqwest-client**: Uses `reqwest` as HTTP client on the `http` APIs. Improves performance, but increases the bundle size.
 //! - **native-tls-vendored**: Compile and statically link to a vendored copy of OpenSSL (applies to the default HTTP client).
 //! - **reqwest-native-tls-vendored**: Compile and statically link to a vendored copy of OpenSSL (applies to the `reqwest` HTTP client).
+//! - **os-api**: Enables the [`api::os`] module.
 //! - **process-command-api**: Enables the [`api::process::Command`] APIs.
 //! - **global-shortcut**: Enables the global shortcut APIs.
 //! - **clipboard**: Enables the clipboard APIs.
@@ -897,6 +898,7 @@ mod tests {
       "fs-extract-api",
       "http-api",
       "http-multipart",
+      "os-api",
       "process-command-api",
       "process-relaunch-dangerous-allow-symlink-macos",
       "window-data-url",

tooling/api/src/os.ts

@@ -160,5 +160,27 @@ async function tempdir(): Promise<string> {
   })
 }
 
-export { EOL, platform, version, type, arch, tempdir }
+/**
+ * Returns a String with a `BCP-47` language tag inside. If the locale couldn’t be obtained, `null` is returned instead.
+ * @example
+ * ```typescript
+ * import { locale } from '@tauri-apps/api/os';
+ * const locale = await locale();
+ * if (locale) {
+ *    // use the locale string here
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+async function locale(): Promise<string | null> {
+  return invokeTauriCommand<string>({
+    __tauriModule: 'Os',
+    message: {
+      cmd: 'locale'
+    }
+  })
+}
+
+export { EOL, platform, version, type, arch, tempdir, locale }
 export type { Platform, OsType, Arch }