Write text.
Ship anywhere.

Load a language when it is needed

Pass one async loader per locale. Creating a store performs no fetch. Await setLocale(null) to load the first supported preference from languages, or defaultLocale if none match.

import { createLocon } from 'locon/core'

const i18n = createLocon({
  defaultLocale: 'en',
  languages: ['de-AT', 'en'],
  loaders: {
    en: () => import('./i18n/en.json'),
    de: () => import('./i18n/de.json'),
  },
})

await i18n.setLocale(null) // loads de only
await i18n.setLocale('en') // loads en once
await i18n.setLocale('de') // uses cached de
i18n.l('Good morning') // 'Guten Morgen' (phrase-indexed resources)

Successful loads are cached and parallel loads are deduplicated. The last selection wins. Failed loads reject, expose an error and keep the displayed language; catch the rejection and allow retry. A superseded selection resolves false.

Connect the store to React

Pass a loaded instance to LoconProvider. The hook subscribes to locale, loading and error changes. This adapter requires React 19+ and never imports React Native.

import { L, LoconProvider, useLocon } from 'locon/react'

// Bootstrap before mounting:
await i18n.setLocale(null)

// Inside your React tree:
<LoconProvider instance={i18n}>
  <App />
</LoconProvider>

// Inside a child component:
const { l, currentLocale, loading, error, setLocale } = useLocon()
l('Good morning') // string props and metadata
<h1><L>Good morning</L></h1>
<h2><L params={{ name }}>{'Hello {name}'}</L></h2>

L returns text without a wrapping HTML element, including inside SVG text. It supports params, count, locale and fallback. Keep l() for string props. Use source phrases as resource keys for lazy apps; reverse lookup against separate keys needs the source resource loaded. On the server, keep each mutable store scoped to one request.

React Native: provide locales once

Pass the imported resource objects to the provider. projectLocale is the language used for plain text in your source code. Keep the assets map stable instead of rebuilding it during render, so locale detection and Locon's reverse index stay cached.

const assets = { de, en }

<Locon
  assets={assets}
  projectLocale='de'
  defaultLocale='en'
>
  <App />
</Locon>

assets

Locale → flat string object

projectLocale

Language written inside components

defaultLocale

Fallback locale, defaults to en

currentLocale

Explicit locale; null re-enables autodetect

autodetect

Detect device language, enabled by default

Write the actual interface text

Locon finds the matching key by value in the project locale, then reads that key from the current locale. Missing values fall back per key to the default and project locales; unresolved input renders as-is.

import { LText } from 'locon'

<LText>Guten Morgen</LText>

// Explicit keys still work when you need one.
<LText assetKey='greeting'>Hello</LText>

React Native: translate and switch locale

Use the hook outside text components or to build your own language selector.

const {
  l,
  currentLocale,
  setLocale,
} = useLocon()

l('Guten Morgen')
setLocale('en')

l(value)

Resolve a key or project-language value

currentLocale

Currently selected locale code

setLocale(locale | null)

Switch locale or resume autodetection

React Native: follow the device language

With autodetect enabled, Locon finds the best available locale. On Expo it reads expo-localization; in bare React Native, react-native-localize. Both are optional — without either, Locon falls back to native APIs and Intl before using the default locale.

# Expo
npx expo install expo-localization

# bare React Native
npm install react-native-localize
cd ios && pod install

Matching starts with the exact tag, then preserves an explicit or region-implied script before widening to a bare language or another locale in that language. So pt can land on pt-BR, while zh-TW and zh-Hant-TW choose zh-Hant over zh-Hans.

Interpolation and plurals

Plain interpolation only needs params. Plurals are a separate feature: pass count and suffix keys with the CLDR category the locale actually uses — {count} is interpolated for you. The six possible suffixes are _zero, _one, _two, _few, _many, and _other.

// Plain interpolation — no plural forms needed
{
  "saved_radius": "{m} m radius · saved"
}

l('{m} m radius · saved', { params: { m: 150 } })
// → '150 m radius · saved'

// Plurals: en.json — two forms
{
  "day_one": "{count} day",
  "day_other": "{count} days"
}

// ru.json — four categories
{
  "day_one": "{count} день",
  "day_few": "{count} дня",
  "day_many": "{count} дней",
  "day_other": "{count} дня"
}

// ar.json — all six categories
{
  "day_zero": "لا أيام",       // 0
  "day_one": "يوم واحد",      // 1
  "day_two": "يومان",         // 2
  "day_few": "{count} أيام",  // 3–10 modulo 100
  "day_many": "{count} يومًا", // 11–99 modulo 100
  "day_other": "{count} يوم"   // e.g. 100 or a decimal
}

l('{count} days', { count: 5 }) // en → '5 days' · ru → '5 дней'

// Locon uses Intl.PluralRules for the target locale
const ruPlural = new Intl.PluralRules('ru')
ruPlural.select(21)  // → 'one'
ruPlural.select(22)  // → 'few'
ruPlural.select(25)  // → 'many'
ruPlural.select(1.5) // → 'other'

Which numbers select each category is language-specific; the comments above are examples, not universal ranges. Always provide _other: it is CLDR's catch-all and Locon's first fallback before the bare key. There is deliberately no generic _plural suffix. See the ECMA-402 API specification ↗ and Unicode CLDR Russian rules ↗.

One language for the screen, another for the document

lIn() forces a single lookup into another locale. createTranslator() is the same resolver without React — for a PDF, an export, an e-mail, or a background notification.

import { createTranslator } from 'locon/core'
import { useLocon } from 'locon'

// Inside React: ignore the UI locale for one lookup.
const { lIn } = useLocon()
lIn('tr', 'Arbeitszeit') // → 'Çalışma süresi'

// Outside React: bind a translator to the output locale.
const translateReport = createTranslator({
  assets: { de, tr },
  locale: 'tr', // output language
  defaultLocale: 'de',
  projectLocale: 'de', // language of source phrases
})

translateReport('Arbeitszeit') // → 'Çalışma süresi'

The output locale is independent of the interface: a German UI can still generate a Turkish timesheet, and a Turkish UI can generate a German one.

Right-to-left, on purpose

isRTL on the context tells you the direction of the current locale. applyRTL() aligns React Native's I18nManager and returns true when the direction actually changed — which means a restart is needed before it renders. Locon never restarts your app for you.

import { applyRTL, isRtlLocale } from 'locon'

isRtlLocale('ar-EG') // true — region subtags ignored
isRtlLocale('pa-Arab') // true — an explicit script wins

const needsRestart = applyRTL('ar')

On Expo, set supportsRTL: true in the expo-localization plugin config or iOS ignores the change.

Locale utilities without a provider

resolveLocale() answers "which locale should I show?" with the exact precedence the provider uses — explicit choice, else device, else default. Anything running outside React should ask it rather than re-deriving the rule and eventually disagreeing.

// Native provider helpers; Node uses matchLocale from locon/core.
import { intlLocale, resolveLocale } from 'locon'

resolveLocale({ assets, currentLocale: null })
// device language, else default

intlLocale('fa', { calendar: 'persian' })
// → 'fa-u-ca-persian'

intlLocale('de-u-nu-latn', {
  calendar: 'gregory',
})
// → 'de-u-nu-latn-ca-gregory'

intlLocale() builds tags for Intl. Locon has no opinion on your calendar or numbering system — that is a product decision — but it gets the syntax right, which concatenation does not.