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.
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:
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:
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.