Concepts fondamentaux

18ways a des opinions sur certaines choses. Une fois celles-ci clarifiées, le reste de l'API est simple.

Locale de base

Votre baseLocale est la langue dans laquelle vous écrivez.

Si votre texte produit est rédigé en anglais britannique, votre locale de base est en-GB. S'il est rédigé en anglais américain, votre locale de base est en-US.

Lorsque la locale actuelle correspond à la locale de base, 18ways renvoie immédiatement le texte source et ignore le travail de traduction.

Locale cible

Votre locale cible est la langue que l'utilisateur est en train de lire.

Dans Vanilla JS, vous le définissez directement sur le moteur avec engine.setLocale(...).

Contextes

Les contextes sont la façon dont 18ways regroupe des copies liées.

Utilisez-les pour garder les demandes de traduction petites et éviter de mélanger des textes non liés.

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',
  }
);

Utilisez des noms de contexte stables afin que les textes associés restent regroupés.

Langues acceptées

18ways distingue entre :

• une locale qu'il peut reconnaître, comme fr-FR
• une locale que votre projet accepte réellement

Dans le package principal, vous conservez généralement cette liste de locales acceptées dans votre propre application et normalisez avant d'appeler 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);
}

Persévérance

Le cookie de préférence de locale utilisé par les adaptateurs d'exécution est 18ways_locale.

Si vous persistez à localiser vous-même et souhaitez rester compatible avec les couches React ou Next, utilisez le même nom.

Lorsque les traductions se chargent

@18ways/core vous fournit le moteur de bas niveau et la mise en cache, mais vous contrôlez le flux de rendu.

Modèle mental partagé

Gardez le modèle simple :

1. Choisissez le bon package pour votre application.
2. Définissez correctement la locale de base.
3. Gardez les clés de contexte stables et significatives.
4. Laissez le runtime traduire des phrases complètes, pas des fragments.

Suivant : Formatage des messages