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 React, you usually hold it in state and pass it to the root Ways.

Contexts

Contexts are how 18ways groups related copy.

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

import { Ways } from '@18ways/react';
 
export function AppRoot() {
  return (
    <Ways
      apiKey="YOUR_18WAYS_PUBLIC_API_KEY"
      locale="fr-FR"
      baseLocale="en-GB"
      context="marketing"
    >
      <Ways context="hero">
        <Hero />
      </Ways>
      <Ways context="pricing">
        <Pricing />
      </Ways>
    </Ways>
  );
}

Nested Ways scopes compose into one context path. marketing plus hero becomes marketing.hero.

Accepted locales

18ways distinguishes between:

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

The runtime can fetch the accepted locale list from the API, then normalize incoming locale values against that list.

import { Ways } from '@18ways/react';
 
export function AppRoot() {
  return (
    <Ways
      apiKey="YOUR_18WAYS_PUBLIC_API_KEY"
      locale="fr-FR"
      baseLocale="en-GB"
      acceptedLocales={[
        'en-GB',
        'fr-FR',
        'de-DE',
      ]}
      context="app"
    >
      <App />
    </Ways>
  );
}

Persistence

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

When translations load

@18ways/react can suspend while a seeded context resolves and keeps a shared in-memory cache on the client.

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