API reference

This document matches @unolio/sdk as of the types in src/ / dist/. Published version: see package.json version.

@unolio/sdk

UnolioOptions

LanguageInfo

Returned by getLanguages() from GET /api/v1/languages (cached on the client after first successful call).

createClient(options: UnolioOptions): UnolioClient

Factory for UnolioClient.

UnolioClient

setLanguage(lang: string): void

Updates the active language used by t, getMessageTemplate, and preload() when called with no arguments.

getLanguage(): string

Returns the current language code.

getLanguages(): Promise<LanguageInfo[]>

Fetches available languages (cached after first completion).

preload(...langs: string[]): Promise<void>

Loads translation JSON for each listed language into the in-memory cache. If langs is empty, preloads getLanguage()’s language.

Concurrency: simultaneous loads for the same language are deduplicated (pending map). Responses respect cacheTtl when reusing cached data.

HTTP: GET {baseUrl}/api/v1/translations?lang={lang}&apiKey=…

t(key: string, vars?: Record<string, string | number>, lang?: string): string

Returns the translated string for key, or key if missing or non-string.

• Nested keys: home.title walks nested objects home → title, unless a single top-level key "home.title" exists (dot or :: in the payload).
• Separators: path segments split on . or :: (see getNestedValue in source); home::title is supported for nesting.
• Interpolation: if vars is provided, {{varName}} in the resolved string is replaced; missing vars leave {{varName}} as literal.

getMessageTemplate(key: string, lang?: string): string

Same resolution as t, without applying vars substitution to {{name}} — used internally by <Trans> so rich markup stays intact until React renders.

DOM helpers

translateDOM(client: UnolioClient, root?: HTMLElement): void

Walks root (default document.body) and updates elements:

No-op when document is undefined (SSR).

switchLanguage(client: UnolioClient, lang: string, root?: HTMLElement): Promise<void>

setLanguage → await preload(lang) → translateDOM(client, root).

@unolio/sdk/react

Peer dependency: react ≥ 17.

UnolioProvider

<UnolioProvider client={client}>{children}</UnolioProvider>

Provides client via React Context. client must satisfy UnolioReactClient (implementations returned by createClient qualify).

useUnolioClient(): UnolioReactClient

Throws if used outside UnolioProvider.

UnolioReactClient

Subset of UnolioClient used by hooks and Trans:

Types: ./client-types.ts.

Trans

Props:

Behavior:

1. Reads getMessageTemplate(i18nKey) when available (else t(i18nKey)).
2. Parses with parseRichMessage (see below).
3. Renders {{vars}} and nested <tags>. Unknown tags with children unwrap to inner content only; self-closing unknown tags yield nothing.

Must be rendered under UnolioProvider.

parseRichMessage(str: string): RichContentNode[]

Parses a string into segments:

• Plain text
• {{var}} variables (names must match /^\w+$/) — mismatches stay as literal text chunks
• <tag>...</tag> and <tag /> — tag names [\w-]+, nesting supported

Exported for advanced/testing use; Trans already uses this.

RichContentNode

type RichContentNode =
  | { type: 'text'; text: string }
  | { type: 'var'; name: string }
  | { type: 'tag'; tag: string; children: RichContentNode[]; selfClosing: boolean };

UnolioReactContext

Low-level React.Context for the client; normally you use UnolioProvider / useUnolioClient only.

UMD global (browser <script>)

When using dist/unolio.umd.js, window.Unolio exposes at least createClient, translateDOM, and switchLanguage. Script auto-init behavior is documented in Script tag & DOM.