Conceitos fundamentais

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

Localidade base

Seu baseLocale é o idioma em que você escreve.

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

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

Localidade alvo

O seu local de destino é o idioma que o usuário está lendo atualmente.

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

Contextos

Contextos são como os grupos do 18ways relacionam-se com o texto.

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

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

Use nomes de contexto estáveis para que textos relacionados permaneçam agrupados.

Locais aceitos

18ways distingue entre:

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

No pacote principal, você geralmente mantém essa lista de locais aceitos em seu próprio aplicativo e normaliza antes de chamar 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);
}

Persistência

O cookie de preferência de localidade usado pelos adaptadores de tempo de execução é 18ways_locale.

Se você persistir em localizar a si mesmo e quiser permanecer compatível com as camadas React ou Next, use o mesmo nome.

Quando as traduções carregam

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

Modelo mental compartilhado

Mantenha o modelo simples:

1. Escolha o pacote correto para o seu aplicativo.
2. Defina o locale base corretamente.
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 Mensagem