useI18nKeyless()

The useI18nKeyless hook provides direct access to the i18n-keyless store state. This hook allows you to access configuration, translations state, and other internal properties using a selector function.

Function Signature

// docs-check: skip — a signature listing, not a snippet to run
useI18nKeyless<T>(selector: (state: TranslationStore) => T): T

Parameters

selector

type: (state: TranslationStore) => T (required)

A function that takes the store state and returns the specific part you need. This follows the Zustand store pattern for optimal performance by only subscribing to the selected slice of state.

Under SSR (≥ 3.3.0) a selector reads the real store on the server and on the hydration render — what init() and hydrateFromServer() put there — not zustand's initial state.

Store Properties

The store contains the following main properties:

config.languages

Access to the language configuration:

• config.languages.primary - The primary language (PrimaryLang)
• config.languages.supported - Array of supported languages (Lang[])
• config.languages.fallback - Optional fallback language (Lang)
• config.languages.initWithDefault - Optional initial language (Lang)

translations

type: Record<string, string>

The current translations map (a fresh object on every refresh). Subscribing to it is the recommended way to make a component that calls the non-reactive getTranslation re-render when translations arrive:

const translations = useI18nKeyless((state) => state.translations);

lastRefresh

type: string | null

Timestamp of the last translations fetch. Prefer subscribing to translations for re-renders: lastRefresh is not set when translations hydrate from local storage at boot, and doesn't change when several namespaces refresh with the same timestamp.

Basic Usage

Language Configuration

import { useI18nKeyless } from 'i18n-keyless-react';

export function LanguageInfo() {
  const primary = useI18nKeyless((store) => store.config.languages.primary);
  const supported = useI18nKeyless((store) => store.config.languages.supported);
  const fallback = useI18nKeyless((store) => store.config.languages.fallback);

  return (
    <div>
      <p>Primary language: {primary}</p>
      <p>Supported languages: {supported.join(', ')}</p>
      <p>Fallback language: {fallback || 'None'}</p>
    </div>
  );
}

Force Re-render

import { useI18nKeyless, getTranslation } from 'i18n-keyless-react';
import ReactMarkdown from 'react-markdown';

export function MarkdownText({ children }) {
  // getTranslation is not reactive: subscribe so this re-renders when translations change
  useI18nKeyless((state) => state.translations);
  const text = getTranslation(children);

  return (
    <ReactMarkdown key={text}>
      {text}
    </ReactMarkdown>
  );
}

Fallback Language

import { useCurrentLanguage, useI18nKeyless } from 'i18n-keyless-react';

export function LanguageDisplay() {
  const currentLanguage = useCurrentLanguage();
  const primary = useI18nKeyless((store) => store.config.languages.primary);
  
  const displayLanguage = currentLanguage || primary;

  return (
    <div>
      Active language: {displayLanguage}
    </div>
  );
}

Combined Access

import { useI18nKeyless } from 'i18n-keyless-react';

export function I18nStatus() {
  const { primary, supported, fallback } = useI18nKeyless((store) => ({
    primary: store.config.languages.primary,
    supported: store.config.languages.supported,
    fallback: store.config.languages.fallback,
  }));

  return (
    <div>
      <h3>i18n Configuration</h3>
      <ul>
        <li>Primary: {primary}</li>
        <li>Languages: {supported.length}</li>
        <li>Fallback: {fallback || 'Not set'}</li>
      </ul>
    </div>
  );
}

Common Use Cases

• Configuration display: Showing current language settings to users
• Force re-renders: Subscribing to translations so components using getTranslation (or react-markdown) update on refresh
• Fallback logic: Implementing custom fallback behavior when current language is null
• Conditional features: Enabling/disabling features based on language configuration
• Debug information: Displaying store state for debugging purposes

Notes

• Uses the selector pattern for optimal performance - only re-renders when selected state changes
• Must be used within a React component (it's a hook)
• The selector function should be stable to avoid unnecessary re-renders
• Access to internal store state - use sparingly and prefer specific hooks like useCurrentLanguage() when available
• Perfect for complex scenarios where you need multiple pieces of store state