@localey/js

JavaScript and TypeScript Runtime SDK for Localey.

The @localey/js package is an ultra-lightweight, zero-dependency SDK designed to perform string resolution and interpolation at runtime. It is the primary runtime for web applications using React, Svelte, or vanilla JavaScript.

Setup and Initialization

To use the SDK, you must initialize it with your locale-specific translations.

import { init, t } from "@localey/js";
import enTranslations from "./locales/en.json";

init({
  locale: "en",
  translations: enTranslations,
});

Core Functionality

String Translation

The t() function is the primary interface for retrieving localized content. It supports nested key access using dot notation.

// For a translation object: { "auth": { "login": "Sign In" } }
t("auth.login"); // Returns: "Sign In"

Parameter Interpolation

The SDK supports dynamic value insertion through a parameter object.

// For a translation string: "Hello {name}!"
t("greeting", { name: "Alice" }); // Returns: "Hello Alice!"

Type-Safe Integration

When combined with the Localey CLI's types command, you can use generated key maps to ensure that only valid keys are passed to the t() function, providing compile-time verification of your localization logic.

Technical Specifications

• Performance: Constant-time lookup for flat objects and efficient traversal for nested structures.
• Size: Minimized bundle footprint suitable for high-performance frontend applications.
• Compatibility: Compatible with all modern browsers and Node.js environments.