soon-i18n-common v2.0

Shared core utilities and type definitions for soon-i18n ecosystem. This package contains the common logic used by all framework-specific adapters.

Purpose

This package provides:

• 🧩 Core Utilities: Shared functions like formatString, flatTreeKey, mergeLocales
• 🎯 Type Definitions: Advanced TypeScript types for type-safe translations
• ⚡ Loading Logic: Universal async/sync loading mechanisms
• 🔧 Framework Agnostic: Can be used standalone for custom integrations

Installation

npm install soon-i18n-common

Core APIs

Utility Functions

formatString(str, obj)

Format a string with placeholders.

import { formatString } from "soon-i18n-common";

const result = formatString("Hello {name}!", { name: "World" });
// Returns: "Hello World!"

flatTreeKey(obj)

Flatten nested object to dot-notation keys.

import { flatTreeKey } from "soon-i18n-common";

const flat = flatTreeKey({
  button: {
    submit: "Submit",
    cancel: "Cancel"
  }
});
// Returns: { "button.submit": "Submit", "button.cancel": "Cancel" }

mergeLocales(target, ...sources)

Safely merge multiple locale objects.

import { mergeLocales } from "soon-i18n-common";

const result = mergeLocales(
  {},
  { welcome: "Welcome" },
  { button: { submit: "Submit" } }
);
// Returns: { welcome: "Welcome", button: { submit: "Submit" } }

formatObjKey(messages, id, ...args)

Get formatted translation from messages object.

import { formatObjKey } from "soon-i18n-common";

const messages = { greeting: "Hello {name}!" };
const result = formatObjKey(messages, "greeting", { name: "World" });
// Returns: "Hello World!"

loadLocale(rawData, onSuccess, onFail)

Load locale resource (sync or async).

import { loadLocale } from "soon-i18n-common";

loadLocale(
  () => import("./locales/en"),
  (locale) => console.log("Loaded:", locale),
  (error) => console.error("Failed:", error)
);

loadSyncLocales(rawLocales)

Load synchronous locales and initialize loading states.

import { loadSyncLocales } from "soon-i18n-common";

const [locales, loadings] = loadSyncLocales({
  zh: { hello: "你好" },
  en: () => import("./locales/en")
});

yi(locale)

Create standalone translator without state.

import { yi } from "soon-i18n-common";

const t = yi({
  hello: "Hello {name}!"
});

console.log(t("hello", { name: "World" })); // "Hello World!"

Type Definitions

AllPaths<T>

Extract all nested paths from an object type.

type Paths = AllPaths<{
  button: {
    submit: string;
    cancel: string;
  }
}>;
// Returns: "button.submit" | "button.cancel"

GetValue<data, path>

Get value type at specific path.

type Value = GetValue<
  { button: { submit: string } },
  "button.submit"
>;
// Returns: string

GetParams<T>

Extract parameters needed for translation.

type Params = GetParams<"Hello {name}, welcome to {city}!">;
// Returns: [{ name: string | number; city: string | number }]

SafeLocales<T>

Get intersection of translation keys across all languages.

type SafeKeys = SafeLocales<{
  zh: { common: { title: string } };
  en: { common: { title: string } };
}>;
// Ensures only keys that exist in ALL languages

LoadingStatus

Type for loading status: undefined | true | false | null

• undefined: Waiting to load
• true: Loading in progress
• false: Loaded successfully
• null: Load failed

Usage Examples

Custom Integration

You can use these utilities to build your own i18n solution:

import { 
  formatString, 
  flatTreeKey, 
  mergeLocales,
  loadLocale 
} from "soon-i18n-common";

class MyI18n {
  private locales = {};
  
  async load(lang: string, loader: () => Promise<any>) {
    await loadLocale(loader, (locale) => {
      this.locales[lang] = flatTreeKey(locale);
    });
  }
  
  translate(key: string, params?: any) {
    const message = this.locales[currentLang][key];
    return params ? formatString(message, params) : message;
  }
}

Type-Safe Translation Function

import { yi, AllPaths, GetValue, GetParams } from "soon-i18n-common";

type Locale = {
  greeting: "Hello {name}!";
  button: {
    submit: "Submit";
  };
};

const t = yi<Locale>({
  greeting: "Hello {name}!",
  button: {
    submit: "Submit"
  }
});

// Full type safety
t("greeting", { name: "World" }); // ✅
t("button.submit");               // ✅
// t("invalid.key");              // ❌ Type error

For Framework Authors

If you're building a framework-specific adapter, you'll need:

import {
  formatString,
  flatTreeKey,
  mergeLocales,
  loadLocale,
  loadSyncLocales,
  formatObjKey,
  yi,
  type AllPaths,
  type GetValue,
  type GetParams,
  type SafeLocales,
  type LoadingStatus
} from "soon-i18n-common";

// Then add your framework's reactivity system

See the source code of soon-i18n-react, soon-i18n-vue, etc. for examples.

Documentation

• 📖 Full Documentation
• 📖 中文文档

License

MIT