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 Next.js, o adaptador pode resolvê-lo a partir de middleware, cookies, o pathname e preferências do navegador.

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.

tsx
'use client';
 
import { Ways } from '@18ways/react';
 
export function MarketingPage() {
  return (
    <Ways context="marketing">
      <Ways context="hero">
        <Hero />
      </Ways>
      <Ways context="pricing">
        <Pricing />
      </Ways>
    </Ways>
  );
}

Escopos Ways aninhados se compõem em um único caminho de contexto. marketing mais hero se torna marketing.hero.

Locais aceitos

18ways distingue entre:

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

O tempo de execução pode buscar a lista de locais aceitos da API e, em seguida, normalizar os valores de localidade recebidos em relação a essa lista.

É por isso que @18ways/next pode fazer coisas sensatas como redirecionar /en-US/docs para /en-GB/docs quando apenas en-GB está habilitado.

ts
import type { WaysConfig } from '@18ways/next/config';
 
export default {
  apiKey: 'pk_dummy_demo_token',
  baseLocale: 'en-GB',
  router: 'app', // 'app', 'path', or 'none' depending on if you use app router, path router, or if you don't want the router to sync with locale at all
} satisfies WaysConfig;

Persistência

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

Quando as traduções carregam

@18ways/next pode resolver o locale no servidor, semear traduções de contexto e emitir metadados traduzidos.

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

Conceitos básicos