Atum Localization

A lightweight, TypeScript-first localization library for React applications. It provides runtime language switching, fallback language support, browser language detection, configurable language persistence, and a simple API built on React's useSyncExternalStore.

---

Features

• Runtime language switching
• Fallback language support
• Browser language detection
• Configurable language persistence
• LocalStorage and SessionStorage support
• Locale fallback matching
• React Context integration
• TypeScript support
• Lightweight with no external localization dependencies
• Built using useSyncExternalStore for efficient updates

---

Installation

npm install atum-localization

---

Requirements

• React 18 or later
• React DOM 18 or later

---

Getting Started

1. Create Translation Resources

// locales/en.ts

export default {
  TITLE: "Atum Localization",
  LOGIN: "Login",
  SAVE: "Save",
  CANCEL: "Cancel",
  LANGUAGE: "Language",
};

// locales/ta.ts

export default {
  TITLE: "அட்டம் லோக்கலைசேஷன்",
  LOGIN: "உள்நுழை",
  SAVE: "சேமி",
  CANCEL: "ரத்து",
  LANGUAGE: "மொழி",
};

---

2. Create the Localization Instance

import { createLocalization } from "atum-localization";

import en from "./locales/en";
import ta from "./locales/ta";

export const localization = createLocalization({
  defaultLanguage: "en",
  fallbackLanguage: "en",
  resources: {
    en,
    ta,
  },
});

---

3. Enable Language Detection

Atum Localization can automatically determine the initial language using the user's saved language preference or browser locale.

export const localization = createLocalization({
  defaultLanguage: "en",
  fallbackLanguage: "en",

  resources: {
    en,
    ta,
  },

  detection: {
    enabled: true,
    storage: "local",
    storageKey: "atum-localization-language",
  },
});

Detection Priority

When detection is enabled, the library checks languages in this order:

1. Previously stored language
2. Browser language
3. defaultLanguage

A stored language is only used when it exists in the configured resources.

Browser locales support regional matching.

For example:

Browser locale: ta-IN

Exact match:
ta-IN → if available

Base language:
ta → if ta-IN is not available

Default:
defaultLanguage → if neither is available

Storage Options

Local Storage

detection: {
  enabled: true,
  storage: "local",
}

The selected language is persisted across browser sessions.

Session Storage

detection: {
  enabled: true,
  storage: "session",
}

The selected language is persisted for the current browser session.

No Persistence

detection: {
  enabled: true,
  storage: "none",
}

The language is not persisted.

Custom Storage Key

detection: {
  enabled: true,
  storage: "local",
  storageKey: "my-app-language",
}

The default storage key is:

atum-localization-language

When a user explicitly changes the language using setLanguage(), the selected language is persisted according to the configured storage option.

---

4. Wrap Your Application

import ReactDOM from "react-dom/client";

import {
  LocalizationProvider,
} from "atum-localization";

import { localization } from "./localization";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <LocalizationProvider localization={localization}>
    <App />
  </LocalizationProvider>
);

---

5. Translate Content

import { useTranslation } from "atum-localization";

export default function Home() {
  const { t } = useTranslation();

  return (
    <>
      <h1>{t("TITLE")}</h1>
      <button>{t("LOGIN")}</button>
      <button>{t("SAVE")}</button>
      <button>{t("CANCEL")}</button>
    </>
  );
}

---

6. Change Language

import { useLanguage } from "atum-localization";

export default function LanguageSelector() {
  const { language, setLanguage } = useLanguage();

  return (
    <select
      value={language}
      onChange={(e) => setLanguage(e.target.value)}
    >
      <option value="en">English</option>
      <option value="ta">Tamil</option>
    </select>
  );
}

When language detection is enabled, an explicitly selected language is persisted according to the configured storage option.

---

API Reference

createLocalization(options)

Creates a localization instance.

const localization = createLocalization({
  defaultLanguage: "en",
  fallbackLanguage: "en",
  resources: {
    en,
    ta,
  },
});

Options

Property	Type	Description
defaultLanguage	string	Initial application language and final detection fallback
fallbackLanguage	string	Language used when a translation is missing
resources	LocalizationResources	Translation resources
detection	LanguageDetectionOptions	Browser language detection and persistence configuration

---

detection

interface LanguageDetectionOptions {
  enabled?: boolean;
  storage?: "local" | "session" | "none";
  storageKey?: string;
}

Property	Type	Default	Description
enabled	boolean	false	Enables browser language detection and persistence
storage	"local" | "session" | "none"	"local"	Controls where the selected language is persisted
storageKey	string	"atum-localization-language"	Storage key used to persist the language

---

LocalizationProvider

Provides the localization instance to the React component tree.

<LocalizationProvider localization={localization}>
  <App />
</LocalizationProvider>

---

useTranslation()

Returns the translation function.

const { t } = useTranslation();

t("LOGIN");

---

useLanguage()

Returns the current language and a function to change it.

const { language, setLanguage } = useLanguage();

setLanguage("ta");

---

Public Exports

import {
  createLocalization,
  LocalizationProvider,
  useTranslation,
  useLanguage,
} from "atum-localization";

---

Fallback Behavior

If a translation is not available in the current language, the library searches the configured fallback language.

If the translation is still not found, the translation key itself is returned.

Example:

t("UNKNOWN_KEY");

Output:

UNKNOWN_KEY

---

Package Structure

src/
├── core/
├── hooks/
├── provider/
├── types/
├── constants/
├── utils/
├── index.ts
└── version.ts

---

Current Features

• Runtime language switching
• Translation lookup
• Fallback language support
• Browser language detection
• Configurable language persistence
• LocalStorage and SessionStorage support
• Locale fallback matching
• React Context integration
• React hooks
• TypeScript declarations
• ESM and CommonJS builds

---

Planned Features

• Variable interpolation
• Nested translation keys
• Type-safe translation keys
• Lazy-loaded language resources
• Pluralization support

---

License

MIT