Conceptos básicos

18ways tiene opiniones claras sobre algunas cosas. Una vez que estas estén claras, el resto de la superficie de la API es sencilla.

Configuración regional base

Tu baseLocale es el idioma en el que escribes.

Si la copia de tu producto está escrita en inglés británico, tu configuración regional base es en-GB. Si está escrita en inglés americano, tu configuración regional base es en-US.

Cuando la configuración regional actual coincide con la configuración regional base, 18ways devuelve el texto original de inmediato y omite el trabajo de traducción.

Idioma de destino

Tu idioma objetivo es el idioma que el usuario está leyendo actualmente.

En Vanilla JS, lo estableces directamente en el motor con engine.setLocale(...).

Contextos

Los contextos son cómo los grupos de 18ways relacionan el contenido.

Úselos para mantener las solicitudes de traducción pequeñas y evitar mezclar texto no relacionado.

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

Utiliza nombres de contexto estables para que el texto relacionado se mantenga agrupado.

Locales aceptados

18ways distingue entre:

  • un locale que puede reconocer, como fr-FR
  • un idioma que tu proyecto realmente acepta

En el paquete principal, normalmente mantienes esa lista de locales aceptados en tu propia aplicación y normalizas antes de llamar a engine.setLocale(...).

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

Persistencia

La cookie de preferencia de localización utilizada por los adaptadores de tiempo de ejecución es 18ways_locale.

Si persistes en la localización y quieres mantener la compatibilidad con las capas de React o Next, utiliza el mismo nombre.

Cuando se cargan las traducciones

@18ways/core te proporciona el motor de bajo nivel y la caché, pero tú controlas el flujo de renderizado.

Modelo mental compartido

Mantén el modelo simple:

  1. Elige el paquete correcto para tu aplicación.
  2. Establece correctamente la configuración regional base.
  3. Mantén las claves de contexto estables y significativas.
  4. Deja que el tiempo de ejecución traduzca frases completas, no fragmentos.

Siguiente: Formato de Mensaje