@harjs/translation
v1.0.1
Published
A simple, lightweight and type-safe translation manager for JavaScript and TypeScript applications.
Maintainers
kaan.cetinReadme
@harjs/translation
A simple, lightweight, and type-safe translation manager for JavaScript and TypeScript applications. Works perfectly with React, Next.js (App Router / Pages Router), and supports dynamic string formatting.
Features
- React & Next.js Ready: Fully compatible with Client Components (
"use client"). - Type-Safe: Full TypeScript support for your translation keys with IntelliSense and auto-completion.
- Zero External Dependencies: Lightweight and optimized for performance.
- Dynamic Formatting: Seamlessly inject dynamic values into translation strings using
{0},{1}, and other placeholders.
Installation
npm install @harjs/translationUsage Guide
1. Define Your Translations and Types
Create your dictionary files and define a base type to ensure type safety across your application.
locales/tr.ts
export const tr = {
welcome: "Hoş geldiniz, {0}!",
logout: "Çıkış Yap",
items_count: "Sepetinizde {0} adet {1} var.",
};
export type BaseLocale = typeof tr;locales/en.ts
import type { BaseLocale } from "./tr";
export const en: Partial<BaseLocale> = {
welcome: "Welcome, {0}!",
logout: "Logout",
items_count: "You have {0} {1} in your cart.",
};locales/index.ts
import { tr } from "./tr";
import { en } from "./en";
export const translations = {
tr,
en,
};2. Set Up the LanguageProvider
Wrap your application with LanguageProvider to manage the active language globally.
Next.js Example (app/layout.tsx)
import { LanguageProvider } from "@harjs/translation";
export default function RootLayout({ children }: { children: React.ReactNode }) {
const currentLang = "tr"; // Retrieve from cookies, URL parameters, or state.
return (
<html lang={currentLang}>
<body>
<LanguageProvider language={currentLang}>{children}</LanguageProvider>
</body>
</html>
);
}3. Use in Components
Use useLanguage to access the current language and useTranslation to perform type-safe translations.
"use client";
import React from "react";
import { useLanguage, useTranslation } from "@harjs/translation";
import { translations } from "./locales";
import type { BaseLocale } from "./locales/tr";
export default function ProfileComponent() {
const currentLang = useLanguage();
const { t } = useTranslation<BaseLocale>(currentLang, translations);
return (
<div>
<h1>{t("welcome", "Kaan")}</h1>
<p>{t("items_count", 3, "products")}</p>
<button>{t("logout")}</button>
</div>
);
}API Reference
<LanguageProvider language={string | undefined} />
A React Context provider that stores and exposes the active language code ("tr", "en", etc.).
Props
| Prop | Type | Description |
| ---------- | --------------------- | ----------------------------------- |
| language | string \| undefined | The currently active language code. |
useLanguage()
Returns the current language code defined by LanguageProvider.
Return Type
string | undefined;Example
const currentLanguage = useLanguage();useTranslation<TBaseLocale>(currentLanguage, translations)
Merges translation dictionaries and returns a type-safe translation function.
Parameters
currentLanguage
string | undefined;The active language code, typically provided by useLanguage().
translations
Record<string, Record<string, any>>;An object containing your translation dictionaries.
Returns
{
t: (key, ...args) => string;
currentLanguage: string | undefined;
}t(key, ...args)
Returns the translated string for the specified key and replaces placeholders ({0}, {1}, etc.) with the provided arguments.
Examples
t("logout");
// Output: "Logout"
t("welcome", "Kaan");
// Output: "Welcome, Kaan!"
t("items_count", 3, "products");
// Output: "You have 3 products in your cart."currentLanguage
const { currentLanguage } = useTranslation(language, translations);License
MIT License