@harpy-js/i18n

Lightweight i18n utilities and NestJS integration for Harpy.js apps.

This package provides a server-side i18n module, request-scoped locale handling, a CurrentLocale decorator, and the t translation helper used in templates and controllers.

Features

• NestJS I18nModule with lazy-loaded dictionaries
• CurrentLocale decorator for controllers/services
• t() helper for typed translation lookups
• Optional request interceptor to attach locale to the request

Install

npm install @harpy-js/i18n
# or
pnpm add @harpy-js/i18n

Quick Start

1. Register the module in your AppModule:

// src/app.module.ts
import { Module } from "@nestjs/common";
import { I18nModule } from "@harpy-js/i18n";

@Module({
  imports: [
    I18nModule.forRoot({
      defaultLocale: "en",
      supportedLocales: ["en", "fr", "ar"],
      dictionaries: {
        en: () => import("./dictionaries/en.json"),
        fr: () => import("./dictionaries/fr.json"),
      },
    }),
  ],
})
export class AppModule {}

2. Use the CurrentLocale decorator in controllers or services:

import { Controller, Get } from "@nestjs/common";
import { CurrentLocale, JsxRender, t } from "@harpy-js/i18n";
import Homepage from "./views/homepage";

@Controller()
export class HomeController {
  @Get()
  @JsxRender(Homepage, { meta: { title: "Welcome" } })
  home(@CurrentLocale() locale: string) {
    // Return data that may be used by your page component
    return { message: t(locale, "home.welcome", { name: "Visitor" }) };
  }
}

3. Use t() inside server-rendered views or helpers:

// src/views/homepage.tsx
import React from "react";
import { t } from "@harpy-js/i18n";

export default function Homepage({ message, locale }) {
  return (
    <div>
      <h1>{message}</h1>
      <p>{t(locale, "home.subtitle")}</p>
    </div>
  );
}

API Reference

• I18nModule.forRoot(options) — configure the i18n module

  • defaultLocale: string
  • supportedLocales: string[]
  • dictionaries: Record<string, () => Promise<Record<string, string>>> (lazy import)

• @CurrentLocale() — decorator that injects the resolved locale (e.g. 'en') into a controller param

• t(locale, key, vars?) — translation helper; key is a dot-separated translation key, vars is an optional object of replacements

Notes

• The module is intentionally small and focused on server-side translations used during SSR. If you need client-side dynamic translations, integrate a client library (for example i18next) and hydrate translations as needed.
• Templates generated by the CLI import CurrentLocale and t from this package.

Contributing

If you want to extend the package, add tests under packages/harpy-i18n/src/__tests__ and follow the repository contribution guidelines.

License

See the repository LICENSE file.