Mensagens e contexto
Escreva mensagens de origem completas, explique o seu significado e insira valores variáveis sem alterar a identidade das mensagens.
Uma mensagem traduzida precisa de informação suficiente para preservar a ação ou o significado por trás das palavras. Escreva o texto de origem completo e explique como é utilizado em context. Forneça nomes, contagens e outros dados variáveis através 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 cadeia de caracteres. TextOptions requer context: string e aceita values?: Record<string, string | number>. O catálogo contém o modelo da frase; a tradução pode deslocar {name} para a posição que a gramática exigir.
Explique o significado de uma mensagem ambígua #
«Guardar» pode significar submeter um formulário ou adicionar um artigo aos favoritos. O contexto distingue estas mensagens, embora 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. Quem traduz pode escolher o verbo adequado para cada ação. Um contexto como «Texto apresentado a um utilizador» não resolve essa ambiguidade; descreva a ação, o público ou a restrição que possa influenciar a formulação.
O extrator regista esta informação no comentário @context do catálogo. Esta informação serve de orientação para a tradução e não aparece na interface. Coloque a terminologia recorrente, as instruções e os requisitos de voz no contexto de tradução do motor de localização e mantenha o significado específico de cada mensagem junto da 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. Junta o contexto, quando não está vazio, ao texto de origem com um separador nulo, normaliza o conteúdo combinado para Unicode NFC e calcula o hash dos respetivos bytes UTF-8.
As representações Unicode canonicamente equivalentes partilham a mesma chave. Alterar a formulação, a pontuação, as maiúsculas e minúsculas, os espaços em branco ou o contexto pode gerar uma nova chave. Os valores não entram no cálculo do hash, pelo que todos os nomes usados na saudação recorrem à mesma entrada de mensagem.
Depois de alterar o texto de origem ou o contexto, volte a executar a extração e verifique as entradas novas e órfãs. Copiar uma tradução para a nova chave sem verificar o seu significado pode manter precisamente a formulação que a alteração do texto de origem pretendia substituir. Os hashes são finitos; o extrator deteta colisões entre as mensagens que recolhe.
Mantenha as chamadas num formato que permita a extração #
Use cadeias de caracteres literais para o texto de origem e o contexto em chamadas como l.text(...). O ambiente de execução pode receber uma cadeia calculada, mas o extrator não consegue inferir todas as cadeias que o programa poderá construir. Mantenha o recetor como l ou como uma variável suportada criada a partir de useLingo ou createLingo. A referência de extração descreve as formas reconhecidas.
Use marcadores de posição para os dados variáveis, em vez de gerar cadeias de origem como "Welcome, " + name. Um modelo estável pode ser extraído, traduzido uma vez por significado e reutilizado para cada valor.
Interpolação e ICU #
Os marcadores de posição simples usam nomes como {name}. Os valores fornecidos são convertidos em texto. Os marcadores simples sem valor permanecem visíveis; se omitir o objeto values, é devolvido o modelo selecionado sem interpolação.
Para construções gramaticais que dependem de uma quantidade ou categoria, o formatador de texto suporta padrões ICU complexos através 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 },
});O resultado é No files. O ramo explícito =0 distingue o zero das categorias de plural habituais do idioma. Forneça todos os argumentos de que o modelo selecionado precisa. Se a análise ou a formatação de padrões ICU complexos falhar, o ambiente de execução devolve esse modelo e comunica um erro de desenvolvimento, sem duplicar o aviso; não substitui uma tradução malformada por uma nova formatação do texto de origem.
Plurais e seleções disponibiliza funções auxiliares para alternativas completas. Texto formatado insere elementos React através de um analisador separado de etiquetas com nome. Use a forma adequada em vez de misturar expressões ICU complexas em modelos de texto formatado.