Mensagens e contexto

Escreva mensagens de origem completas, explique o que significam e insira valores variáveis sem alterar a identidade das mensagens.

Uma mensagem traduzida precisa de informações suficientes para preservar a ação ou o sentido por trás das palavras. Escreva o texto de origem completo e explique como ele é usado em context. Forneça nomes, contagens e outros dados variáveis por meio de values.

tsx
import { useLingo } from "@lingo.dev/react";

export function Greeting({ name }: { name: string }) {
  const l = useLingo();
  return (
    <h1>
      {l.text("Welcome back, {name}.", {
        context: "Greeting at the top of the account dashboard",
        values: { name },
      })}
    </h1>
  );
}

O resultado é uma string. TextOptions exige context: string e aceita values?: Record<string, string | number>. O catálogo contém o modelo da frase; a tradução pode reposicionar {name} conforme as regras gramaticais do idioma.

Explique o sentido de uma mensagem ambígua #

“Salvar” pode significar enviar um formulário ou adicionar um artigo aos favoritos. O contexto diferencia essas mensagens, mesmo que o texto de origem em inglês seja idêntico:

ts
import { computeKey } from "@lingo.dev/react";

const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");

As chaves são diferentes. Assim, quem traduz pode escolher o verbo adequado para cada ação. Um contexto como “Texto exibido ao usuário” não resolve essa ambiguidade; descreva a ação, o público ou a restrição que poderia influenciar a redação.

O extrator grava essas informações no comentário @context do catálogo. Elas orientam a tradução, mas não aparecem na interface. Coloque a terminologia recorrente, as instruções e os requisitos de voz no contexto de tradução do engine de localização e mantenha o significado específico de cada mensagem junto à chamada.

Identidade da mensagem #

computeKey(source: string, context?: string): string gera uma chave de oito caracteres a partir do texto de origem e do contexto. Ele une um contexto não vazio ao texto de origem usando um separador nulo, normaliza a entrada combinada para Unicode NFC e calcula o hash dos bytes em UTF-8.

Representações Unicode canonicamente equivalentes compartilham a mesma chave. Alterações na redação, na pontuação, no uso de maiúsculas e minúsculas, nos espaços em branco ou no contexto podem gerar uma nova chave. Os valores não entram no cálculo do hash, por isso todos os nomes usados na saudação compartilham a mesma entrada de mensagem.

Depois de alterar o texto de origem ou o contexto, execute a extração novamente e examine as entradas novas e órfãs. Copiar uma tradução para a nova chave sem conferir seu significado pode preservar justamente a redação que a alteração no texto de origem pretendia substituir. Os hashes são finitos; o extrator detecta colisões entre as mensagens que coleta.

Mantenha as chamadas extraíveis #

Use strings literais para o texto de origem e o contexto em chamadas como l.text(...). O ambiente de execução pode receber uma string calculada, mas o extrator não consegue inferir todas as strings que o programa pode construir. Mantenha o receptor como l ou como uma variável compatível criada a partir de useLingo ou createLingo. A referência de extração descreve as formas reconhecidas.

Use marcadores de posição para dados variáveis em vez de gerar strings de origem como "Welcome, " + name. Um modelo estável pode ser extraído, traduzido uma vez para cada significado e reutilizado com cada valor.

Interpolação e ICU #

Marcadores de posição simples usam nomes como {name}. Os valores fornecidos são convertidos em texto. Marcadores simples sem valores correspondentes permanecem visíveis; se o objeto values for omitido, o modelo selecionado será retornado sem interpolação.

Para construções gramaticais que dependem de uma quantidade ou categoria, o formatador de texto aceita padrões ICU complexos por meio de intl-messageformat:

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
  context: "Number of files attached to a message",
  values: { count: 0 },
});

Isso retorna No files. A ramificação explícita =0 distingue o zero das categorias de plural habituais do idioma. Forneça todos os argumentos necessários ao modelo selecionado. Se houver falha na análise ou na formatação de padrões ICU complexos, o ambiente de execução retorna esse modelo e relata um erro de desenvolvimento sem duplicá-lo; ele não substitui uma tradução malformada pelo texto de origem formatado novamente.

Plurais e seleções oferece funções auxiliares para alternativas completas. Texto rico insere elementos React por meio de um analisador separado de tags nomeadas. Use a forma adequada em vez de misturar expressões ICU complexas em modelos de texto rico.