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 Next.js, the adapter can resolve it from middleware, cookies, the pathname, and browser preferences.

Contexts

Contexts are how 18ways groups related copy.

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

'use client';
 
import { Ways } from '@18ways/react';
 
export function MarketingPage() {
  return (
    <Ways 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.

That is why @18ways/next can do sensible things like redirect /en-US/docs to /en-GB/docs when only en-GB is enabled.

import { init as initWays } from '@18ways/next/server';
 
const ways = initWays({
  apiKey: 'YOUR_18WAYS_PUBLIC_API_KEY',
  baseLocale: 'en-GB',
  acceptedLocales: [
    'en-GB',
    'fr-FR',
    'de-DE',
  ],
  pathRouting: {
    exclude: ['/dashboard'],
  },
});

Persistence

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

When translations load

@18ways/next can resolve locale on the server, seed context translations, and emit translated metadata.

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