Add docs

pklaschka · pklaschka · commit 2f32e25b6d37 · 2025-11-23T16:11:43.000+01:00
diff --git a/lib/hono/HonolateContext.ts b/lib/hono/HonolateContext.ts
@@ -1,5 +1,8 @@
 import type { LocalizedValue } from "./LocalizedValue.ts";
 
+/**
+ * The context type for Honolate, extending Hono's Context with localization-related variables.
+ */
 export type HonolateContext<T extends string> = {
   Variables: {
     language?: T;
diff --git a/lib/hono/InitHonolateOptions.ts b/lib/hono/InitHonolateOptions.ts
@@ -1,11 +1,23 @@
 import type { JsonPath } from "./JsonPath.ts";
 
+/**
+ * Options for initializing Honolate middleware in a Hono application.
+ */
 export interface InitHonolateOptions<T extends string> {
+  /**
+   * The default language to fall back to when no specific language is set or detected.
+   */
   readonly defaultLanguage: T;
+  /**
+   * A mapping of supported languages to their respective JSON path files containing localization data.
+   */
   readonly languages: Readonly<
     {
       [key in T]: JsonPath;
     }
   >;
+  /**
+   * A global pattern for files to search for localization keys.
+   */
   pattern?: string;
 }
diff --git a/lib/hono/JsonPath.ts b/lib/hono/JsonPath.ts
@@ -1 +1,4 @@
+/**
+ * Path to a JSON file containing localization data.
+ */
 export type JsonPath = string;
diff --git a/lib/hono/LazyLocalyzedString.ts b/lib/hono/LazyLocalyzedString.ts
@@ -1,6 +1,19 @@
 import type { LocalyzedStringValue } from "./LocalyzedStringValue.ts";
 
+/**
+ * A lazily evaluated localized string with a key and optional values for interpolation.
+ *
+ * Gets resolved later – when the locale is known – using the {@link import("t.ts").t} function.
+ */
 export type LazyLocalyzedString = {
+  /**
+   * The localization key used to look up the localized string.
+   */
   localizationKey: string;
+  /**
+   * An array of values to be interpolated into the localized string.
+   *
+   * `"{i}"` gets replaced by the i-th value in this array. `"\{i}"` can be used to escape the `"{"` character.
+   */
   values: LocalyzedStringValue[];
 };
diff --git a/lib/hono/LocalizedValue.ts b/lib/hono/LocalizedValue.ts
@@ -1 +1,6 @@
+/**
+ * A localized string value.
+ *
+ * This is the value of a localization key in the localization JSON files.
+ */
 export type LocalizedValue = string;
diff --git a/lib/hono/LocalyzedStringValue.ts b/lib/hono/LocalyzedStringValue.ts
@@ -1,3 +1,32 @@
 import type { LazyLocalyzedString } from "./LazyLocalyzedString.ts";
 
+/**
+ * A value passed into a localized string for interpolation.
+ *
+ * This can be a string, number, or another {@link LazyLocalyzedString} for nested localization.
+ *
+ * For example, given the localization entry:
+ *
+ * ```json
+ * {
+ *   "greeting": "Hello, {0}!",
+ *   "welcomeMessage": "{0} Welcome to our site."
+ * }
+ * ```
+ *
+ * You could create a `LazyLocalyzedString` for `welcomeMessage` that includes another
+ * `LazyLocalyzedString` for `greeting` as its first value:
+ *
+ * ```ts
+ * const lazyGreeting: LazyLocalyzedString = {
+ *   localizationKey: "greeting",
+ *   values: ["Alice"]
+ * };
+ *
+ * const lazyWelcomeMessage: LazyLocalyzedString = {
+ *   localizationKey: "welcomeMessage",
+ *   values: [lazyGreeting]
+ * };
+ * ```
+ */
 export type LocalyzedStringValue = string | number | LazyLocalyzedString;
diff --git a/lib/hono/ensureLazyLocalyzedString.ts b/lib/hono/ensureLazyLocalyzedString.ts
@@ -2,6 +2,13 @@ import type { LazyLocalyzedString } from "./LazyLocalyzedString.ts";
 import type { LocalyzedStringValue } from "./LocalyzedStringValue.ts";
 import { lt } from "./lt.ts";
 
+/**
+ * Ensures that the input is a LazyLocalyzedString.
+ *
+ * Can be applied to either a template string or an already existing LazyLocalyzedString.
+ *
+ * @returns the input as a LazyLocalyzedString
+ */
 export function ensureLazyLocalyzedString(
   input: TemplateStringsArray | LazyLocalyzedString,
   values: LocalyzedStringValue[],
diff --git a/lib/hono/getLocalizationMap.ts b/lib/hono/getLocalizationMap.ts
@@ -1,6 +1,9 @@
 import { useRequestContext } from "@hono/hono/jsx-renderer";
 import { neverThrow } from "../common/neverThrow.ts";
 
+/**
+ * @returns the current locale's localization map, mapping localization keys to their respective translations
+ */
 export function getLocalizationMap(): Record<string, string> {
   const ctx = neverThrow(() => useRequestContext());
   if (ctx instanceof Error) {
diff --git a/lib/hono/initHonolate.ts b/lib/hono/initHonolate.ts
@@ -6,6 +6,30 @@ import type { InitHonolateOptions } from "./InitHonolateOptions.ts";
 import type { LocalizedValue } from "./LocalizedValue.ts";
 import { ensureRequestLanguage } from "./ensureRequestLanguage.ts";
 
+/**
+ * Initializes Honolate with the given options.
+ *
+ * Make sure to add the returned middleware to your Hono app before any route handlers that use localization.
+ *
+ * @param options the options with which Honolate will be initialized. See {@link InitHonolateOptions}
+ * @returns the middleware required to show localized strings using Honolate
+ *
+ * @example
+ * import { InitHonolateOptions, initHonolate } from '@wuespace/honolate';
+ *
+ * const honolateOptions: InitHonolateOptions<'en' | 'de'> = {
+ *   defaultLanguage: 'en',
+ *   languages: {
+ *     en: './locales/en.json',
+ *     de: './locales/de.json',
+ *   },
+ *   // optional: add custom language detection logic here
+ * };
+ *
+ * const app = new Hono();
+ * app.use('*', initHonolate(honolateOptions));
+ * // ...other middlewares and route handlers
+ */
 export const initHonolate: <T extends string>(
   options: InitHonolateOptions<T>,
 ) => ReturnType<typeof createMiddleware<HonolateContext<T>>> = <
@@ -18,30 +42,7 @@ export const initHonolate: <T extends string>(
   const languages = new Map<T, Record<string, LocalizedValue>>();
 
   for (const lang in options.languages) {
-    const path = options.languages[lang as T];
-    const module = neverThrow(() => Deno.readFileSync(normalizePath(path)));
-    if (module instanceof Error) {
-      console.error(
-        `Failed to load language file for ${lang} at ${path}:`,
-        module,
-      );
-      languages.set(lang as T, {});
-      continue;
-    }
-
-    const decodedModule = new TextDecoder().decode(module);
-    const parsedModule = neverThrow(() => JSON.parse(decodedModule));
-
-    if (parsedModule instanceof Error) {
-      console.error(
-        `Failed to parse language file for ${lang} at ${path}:`,
-        parsedModule,
-      );
-      languages.set(lang as T, {});
-      continue;
-    }
-
-    languages.set(lang as T, parsedModule as Record<string, LocalizedValue>);
+    languages.set(lang, loadLanguage(options.languages[lang]));
   }
 
   return createMiddleware<HonolateContext<T>>(async (c, next) => {
@@ -56,3 +57,39 @@ export const initHonolate: <T extends string>(
     return next();
   });
 };
+
+/**
+ * Loads a language file from the given path.
+ * @param languagePath the path to the language
+ * @returns the loaded localization map
+ */
+function loadLanguage(languagePath: string): Record<string, LocalizedValue> {
+  // Load
+  const module = neverThrow(() =>
+    Deno.readFileSync(normalizePath(languagePath))
+  );
+
+  if (module instanceof Error) {
+    // Handle file read error
+    console.error(
+      `Failed to load language file at ${languagePath}:`,
+      module,
+    );
+    return {};
+  }
+
+  // Parse
+  const decodedModule = new TextDecoder().decode(module);
+  const parsedModule = neverThrow(() => JSON.parse(decodedModule));
+
+  if (parsedModule instanceof Error) {
+    // Handle JSON parse error
+    console.error(
+      `Failed to parse language file at ${languagePath}:`,
+      parsedModule,
+    );
+    return {};
+  }
+
+  return parsedModule as Record<string, LocalizedValue>;
+}
diff --git a/lib/hono/lt.ts b/lib/hono/lt.ts
@@ -2,6 +2,37 @@ import { escapeKey } from "../common/escapeKey.ts";
 import type { LazyLocalyzedString } from "./LazyLocalyzedString.ts";
 import type { LocalyzedStringValue } from "./LocalyzedStringValue.ts";
 
+/**
+ * A template tag function to create a {@link LazyLocalyzedString}.
+ * @returns A {@link LazyLocalyzedString} representing the localization key and its values.
+ *
+ * @example
+ * ```ts
+ * const lazyString = lt`welcomeMessage`;
+ *
+ * const lazyStringWithValues = lt`welcomeMessage, {0}`("Alice");
+ *
+ * const nestedLazyString = lt`greeting, {0}`(
+ *   lt`userName, {0}`("Alice")
+ * );
+ *
+ * // [...in a Hono rendering context...]
+ * <>
+ *   <p>{t(lazyString)}</p>
+ *   <p>{t(lazyStringWithValues)}</p>
+ *   <p>{t(nestedLazyString)}</p>
+ * </>
+ * ```
+ *
+ * @remarks
+ * The existence of these "late" strings is both the inspiration for the library's name,
+ * as well as a core concept of how localization is handled. By deferring the resolution of
+ * localization keys and their values until the rendering phase, we can ensure that the
+ * correct localized strings are used based on the current context (e.g., user language).
+ *
+ * This allows you to, e.g., throw an `Error` with a localized message without needing
+ * to know the user's language at the time the error is created.
+ */
 export function lt(
   strings: TemplateStringsArray,
   ...values: LocalyzedStringValue[]
diff --git a/lib/hono/runLanguageDetector.ts b/lib/hono/runLanguageDetector.ts
@@ -2,6 +2,14 @@ import type { Context } from "@hono/hono";
 import { languageDetector } from "@hono/hono/language";
 import type { InitHonolateOptions } from "./InitHonolateOptions.ts";
 
+/**
+ * Runs the native Hono language detector middleware to set the language
+ * on the context based on the request.
+ *
+ * Uses the default language and supported languages from the Honolate options.
+ * @param options the Honolate options
+ * @param c the request context
+ */
 export async function runLanguageDetector<T extends string>(
   options: InitHonolateOptions<T>,
   c: Context,
diff --git a/lib/hono/t.ts b/lib/hono/t.ts
@@ -4,6 +4,45 @@ import { getLocalizationMap } from "./getLocalizationMap.ts";
 import type { LazyLocalyzedString } from "./LazyLocalyzedString.ts";
 import type { LocalyzedStringValue } from "./LocalyzedStringValue.ts";
 
+/**
+ * Resolves a localized string based on the current localization map.
+
+ * @returns the localized string with placeholders filled in
+ *
+ * Can be used as a template string tag or as a function with a LazyLocalyzedString.
+ *
+ * Can only be called inside a functional component. To use this directly in route handlers,
+ * use {@link asFC} to wrap the handler as a functional component.
+ *
+ * This cannot be used outside of Hono request context (e.g., in plain Deno scripts),
+ * since it relies on the request context to provide the current language's localization map.
+ *
+ * @example Example as template string tag:
+ * ```ts
+ * const greeting = t`greeting.hello.${userName}`;
+ * ```
+ *
+ * @example Example with LazyLocalyzedString:
+ * ```ts
+ * const lls: LazyLocalyzedString = {
+ *   localizationKey: "greeting.hello",
+ *   values: [userName],
+ * };
+ * const greeting = t(lls);
+ * ```
+ *
+ * @example Using with asFC in route handler:
+ * ```ts
+ * import { asFC, t } from '@wuespace/honolate';
+ *
+ * app.get('/greet', c => {
+ *   return c.render(asFC(() => {
+ *     const greeting = t`Hello ${c.req.param('name')}!`;
+ *     return greeting;
+ *   }));
+ * });
+ * ```
+ */
 export function t(
   strings: TemplateStringsArray,
   ...values: LocalyzedStringValue[]
diff --git a/lib/hono/useLocale.ts b/lib/hono/useLocale.ts
@@ -4,6 +4,10 @@ import { neverThrow } from "../common/neverThrow.ts";
 export class LocaleNotFoundError extends Error {}
 export class NoRequestContextError extends Error {}
 
+/**
+ * Returns the current locale code. Must be used within a Hono JSX Renderer context.
+ * @returns the current locale code
+ */
 export function useLocale(): string {
   const ctx = neverThrow(() => useRequestContext());
   if (ctx instanceof Error) {

-Original file line number
+Diff line change
@@ @@ -1 +1,4 @@ @@
 +/**
 + * Path to a JSON file containing localization data.
 + */
 export type JsonPath = string;