feat: i18n composable

README.md

@@ -86,6 +86,8 @@ Returns Kirby's Panel API for making HTTP requests to the backend.
 
 This composable is a simple shortcut to `window.panel.api`.
 
+**Example:**
+
 ```ts
 import { useApi } from "kirbyuse";
 
@@ -100,6 +102,8 @@ Returns the main Panel Vue instance.
 
 This composable is a simple shortcut to `window.panel.app`.
 
+**Example:**
+
 ```ts
 import { useApp } from "kirbyuse";
 
@@ -112,6 +116,8 @@ console.log(app.$root);
 
 Provides block methods for custom block components, including field access and updates.
 
+**Example:**
+
 ```ts
 import { computed, ref, useApi, useBlock, usePanel, watch } from "kirbyuse";
 
@@ -131,6 +137,8 @@ Provides reactive getters and methods to work with content of the current view.
 > [!TIP]
 > Compatible with both Kirby 4 and 5. The returned getters and methods are shimmed for Kirby 4 in a Kirby 4 environment.
 
+**Example:**
+
 ```ts
 import { useContent } from "kirbyuse";
 
@@ -145,12 +153,33 @@ watch(currentContent, (newContent) => {
 update({ excerpt: "Hello, Kirby!" });
 ```
 
+### useI18n
+
+Returns translation utility functions.
+
+> [!NOTE]
+> In most cases, use `window.panel.t` for Kirby's built-in translation function. This composable is useful for custom translation objects, such as those returned by a section's `label` property.
+
+**Example:**
+
+```ts
+const { t } = useI18n();
+
+// Simple string
+t("Hello"); // -> "Hello"
+
+// Translation object
+t({ en: "Hello", de: "Hallo" }); // -> Returns value based on current Panel language
+```
+
 ### usePanel
 
 Returns the reactive Kirby Panel object with type hints.
 
 This composable is a simple shortcut to `window.panel`.
 
+**Example:**
+
 ```ts
 import { usePanel } from "kirbyuse";
 
@@ -169,6 +198,8 @@ See the [section example](#panel-section) for a usage example.
 
 Returns the Vuex store of the Panel app (Kirby 4 only, will not work in Kirby 5).
 
+**Example:**
+
 ```ts
 import { useStore } from "kirbyuse";
 

src/composables/i18n.ts

@@ -0,0 +1,29 @@
+import { usePanel } from "./panel";
+
+/**
+ * Returns translation utility functions.
+ *
+ * @remarks
+ * In most cases, use `window.panel.t` for Kirby's built-in translation function. This composable is useful for custom translation objects, such as those returned by a section's `label` property.
+ *
+ * @example
+ * const { t } = useI18n()
+ *
+ * // Simple string
+ * t("Hello") // -> "Hello"
+ *
+ * // Translation object
+ * t({ en: "Hello", de: "Hallo" }) // -> Returns value based on current Panel language
+ */
+export function useI18n() {
+  const panel = usePanel();
+
+  function t(value?: string | Record<string, string>) {
+    if (!value || typeof value === "string") return value;
+    return value[panel.translation.code] ?? Object.values(value)[0];
+  }
+
+  return {
+    t,
+  };
+}

src/composables/index.ts

@@ -3,6 +3,7 @@ export * from "./app";
 export * from "./block";
 export * from "./compatibility";
 export * from "./content";
+export * from "./i18n";
 export * from "./panel";
 export * from "./section";
 export * from "./store";