Conceitos fundamentais

A 18ways tem opiniões firmes sobre algumas coisas. Uma vez que estas estejam claras, o restante da superfície da API é simples.

Locale base

O seu baseLocale é a língua em que escreve.

Se a cópia do seu produto estiver escrita em inglês britânico, o seu local base é en-GB. Se estiver escrita em inglês americano, o seu local base é en-US.

Quando o locale atual corresponde ao locale base, 18ways retorna o texto original imediatamente e ignora o trabalho de tradução.

Localização alvo

O seu local de destino é a língua que o utilizador está a ler atualmente.

Em Vanilla JS, você define isso diretamente no motor com engine.setLocale(...).

Contextos

Os contextos são como os grupos de 18ways relacionam-se com o texto.

Use-os para manter os pedidos de tradução pequenos e evitar misturar texto não relacionado.

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

Utilize nomes de contexto estáveis para que o texto relacionado permaneça agrupado.

Locais aceites

18ways distingue entre:

  • um local que pode reconhecer, como fr-FR
  • um local que o seu projeto realmente aceita

No pacote principal, normalmente mantém essa lista de locais aceites na sua própria aplicação e normaliza antes de chamar 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);
}

Persistência

O cookie de preferência de localidade utilizado pelos adaptadores de runtime é 18ways_locale.

Se persistir em localizar-se e quiser manter a compatibilidade com as camadas React ou Next, use o mesmo nome.

Quando as traduções carregam

@18ways/core fornece o motor de nível inferior e o cache, mas você controla o fluxo de renderização.

Modelo mental partilhado

Mantenha o modelo simples:

  1. Escolha o pacote correto para a sua aplicação.
  2. Defina corretamente a localidade base.
  3. Mantenha as chaves de contexto estáveis e significativas.
  4. Deixe o tempo de execução traduzir frases completas, não fragmentos.

Próximo: Formatação de Mensagens

Core Concepts