Core concepts

18ways is opinionated about a few things. Once these are clear, the rest of the API surface is straightforward.

Base locale

Your baseLocale is the language you write in.

If your product copy is written in British English, your base locale is en-GB. If it is written in American English, your base locale is en-US.

When the current locale matches the base locale, 18ways returns the source text immediately and skips translation work.

Target locale

Your target locale is the language the user is currently reading.

In Vanilla JS, you set it directly on the engine with engine.setLocale(...).

Contexts

Contexts are how 18ways groups related copy.

Use them to keep translation requests small and to avoid mixing unrelated text together.

import { create18waysEngine } from '@18ways/core/engine';
 
const engine = create18waysEngine({
  apiKey: 'YOUR_18WAYS_PUBLIC_API_KEY',
  baseLocale: 'en-GB',
  locale: 'fr-FR',
  context: 'marketing',
});
 
const heroTitle = await engine.t(
  'Wrap your text. We handle the rest.',
  {
    context: 'marketing.hero',
  }
);
 
const pricingTitle = await engine.t(
  'Simple pricing',
  {
    context: 'marketing.pricing',
  }
);

Use stable context names so related copy stays grouped together.

Accepted locales

18ways distinguishes between:

• a locale it can recognise, like fr-FR
• a locale your project actually accepts

In the core package, you usually keep that accepted locale list in your own app and normalize before calling engine.setLocale(...).

const acceptedLocales = [
  'en-GB',
  'fr-FR',
  'de-DE',
];
 
function setLocale(nextLocale: string) {
  const locale = acceptedLocales.includes(
    nextLocale
  )
    ? nextLocale
    : 'en-GB';
 
  engine.setLocale(locale);
}

Persistence

The locale preference cookie used by the runtime adapters is 18ways_locale.

If you persist locale yourself and want to stay compatible with the React or Next layers, use the same name.

When translations load

@18ways/core gives you the lower-level engine and caching, but you own the rendering flow.

Shared mental model

Keep the model simple:

1. Pick the correct package for your app.
2. Set the base locale correctly.
3. Keep context keys stable and meaningful.
4. Let the runtime translate complete phrases, not fragments.

Next: Message Formatting