Kernkonzepte

18ways hat zu einigen Dingen eine klare Meinung. Sobald diese klar sind, ist der Rest der API-Oberfläche einfach.

Basislokalisierung

Ihre baseLocale ist die Sprache, in der Sie schreiben.

Wenn Ihr Produkttext in britischem Englisch verfasst ist, ist Ihre Basislokalisierung en-GB. Wenn er in amerikanischem Englisch verfasst ist, ist Ihre Basislokalisierung en-US.

Wenn die aktuelle Sprache mit der Basissprache übereinstimmt, gibt 18ways den Quelltext sofort zurück und überspringt die Übersetzungsarbeit.

Zielgebiet

Ihre Zielregion ist die Sprache, die der Benutzer gerade liest.

In Vanilla JS setzen Sie es direkt auf dem Engine mit engine.setLocale(...).

Kontexte

Kontexte sind, wie 18ways verwandte Texte gruppiert.

Verwenden Sie sie, um Übersetzungsanfragen klein zu halten und um zu vermeiden, dass nicht verwandte Texte vermischt werden.

ts
import { create18waysEngine } from '@18ways/core/engine';
 
const engine = create18waysEngine({
  apiKey: 'pk_dummy_demo_token',
  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',
  }
);

Verwenden Sie stabile Kontextnamen, damit verwandte Texte zusammengehalten werden.

Akzeptierte Regionen

18ways unterscheidet zwischen:

  • eine Sprache, die es erkennen kann, wie fr-FR
  • eine Gebietsschema, das Ihr Projekt tatsächlich akzeptiert

Im Kernpaket behalten Sie normalerweise diese akzeptierte Sprachliste in Ihrer eigenen App und normalisieren , bevor Sie engine.setLocale(...) aufrufen.

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

Persistenz

Das Cookie für die Gebietsschema-Präferenz, das von den Laufzeit-Adaptern verwendet wird, ist 18ways_locale.

Wenn Sie sich lokal persistieren und mit den React- oder Next-Schichten kompatibel bleiben möchten, verwenden Sie denselben Namen.

Wenn Übersetzungen geladen werden

@18ways/core bietet Ihnen den niedrigeren Engine- und Caching-Zugang, aber Sie besitzen den Rendering-Fluss.

Geteiltes mentales Modell

Halten Sie das Modell einfach:

  1. Wählen Sie das richtige Paket für Ihre App aus.
  2. Stellen Sie die Basislokalisierung korrekt ein.
  3. Halten Sie die Kontextschlüssel stabil und sinnvoll.
  4. Lassen Sie die Laufzeit vollständige Sätze und nicht Fragmente übersetzen.

Nächste: Nachrichtenformatierung

Core Concepts