Documentation: t Function in hono-intlayer

The t function in the hono-intlayer package is the core utility for providing localized responses in your Hono application. It simplifies internationalization (i18n) by dynamically selecting content based on the user's preferred language.

Overview

The t function is used to define and retrieve translations for a given set of languages. It automatically determines the appropriate language to return based on the client's request settings, such as the Accept-Language header. If the preferred language is unavailable, it gracefully falls back to the default locale specified in your configuration.

Key Features

• Dynamic Localization: Automatically selects the most appropriate translation for the client.
• Fallback to Default Locale: Falls back to a default locale if the client's preferred language isn't available, ensuring continuity in user experience.
• Lightweight and Fast: Designed for high-performance applications, ensuring minimal overhead.
• Strict Mode Support: Enforce strict adherence to declared locales for reliable behavior.

Function Signature

t(translations: Record<string, string>): string;

Parameters

• translations: An object where the keys are locale codes (e.g., en, fr, es-MX) and the values are the corresponding translated strings.

Returns

• A string representing the content in the client's preferred language.

Loading the Internationalization Request Handler

To ensure that the internationalization functionality provided by hono-intlayer works correctly, you must load the internationalization middleware at the beginning of your Hono application. This enables the t function and ensures proper handling of locale detection and translation.

Place the app.use("*", intlayer()) middleware before any routes in your application to ensure that all routes benefit from internationalization:

import { Hono } from "hono";
import { intlayer, t } from "hono-intlayer";

const app = new Hono();

// Load internationalization request handler
app.use("*", intlayer());

// Define your routes after loading the middleware
app.get("/", (c) => {
  return c.text(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
    })
  );
});

Why This is Required

• Locale Detection: The intlayer middleware processes incoming requests to detect the user's preferred locale based on headers, cookies, or other configured methods.
• Translation Context: Sets up the necessary context for the t function to operate correctly, ensuring that translations are returned in the correct language.
• Error Prevention: Without this middleware, using the t function will result in runtime errors because the necessary locale information won't be available.

Usage Examples

Basic Example

Serve localized content in different languages:

app.get("/", (c) => {
  return c.text(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

Client Requests:

• A client with Accept-Language: fr will receive Bienvenue!.
• A client with Accept-Language: es will receive ¡Bienvenido!.
• A client with Accept-Language: de will receive Welcome! (default locale).

Handling Errors

Provide error messages in multiple languages:

app.get("/error", (c) => {
  return c.text(
    t({
      en: "An unexpected error occurred.",
      fr: "Une erreur inattendue s'est produite.",
      es: "Ocurrió un error inesperado.",
    }),
    500
  );
});

Using Locale Variants

Specify translations for locale-specific variants:

app.get("/greet", (c) => {
  return c.text(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

Advanced Topics

Fallback Mechanism

If a preferred locale is unavailable, the t function will fallback to the default locale defined in the configuration:

import { Locales, type IntlayerConfig } from "intlayer";

const config = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

Strict Mode Enforcement

Configure the t function to enforce strict adherence to declared locales:

TypeScript Integration

The t function is type-safe when used with TypeScript. Define a type-safe translations object:

import { type LanguageContent } from "hono-intlayer";

const translations: LanguageContent<string> = {
  en: "Good morning!",
  fr: "Bonjour!",
  es: "¡Buenos días!",
};

app.get("/morning", (c) => {
  return c.text(t(translations));
});

Common Errors and Troubleshooting

Conclusion

The t function is a powerful tool for backend internationalization. By using it effectively, you can create a more inclusive and user-friendly application for a global audience. For advanced usage and detailed configuration options, refer to the documentation.