Verificar os tipos das chamadas de mensagens
Gere e inclua declarações que verificam os textos de origem, os contextos e os valores das mensagens enquanto você edita.
Uma chamada de mensagem pode ser válida em TypeScript e, ainda assim, solicitar a entrada errada do catálogo. Um contexto alterado ou um marcador com erro de digitação pode fazer com que o texto de origem ou {name} apareça na tela. A extração gera declarações que integram as mensagens de origem conhecidas ao sistema de tipos da aplicação.
Gerar e incluir a declaração #
Com a CLI instalada, execute:
npx lingo extract --src src --source-locale enAs saídas padrão são locales/en.jsonc e lingo.d.ts. Adicione lingo.d.ts à lista de inclusão tsconfig já existente na aplicação, caso nenhum dos padrões atuais inclua esse caminho. Mantenha as demais entradas:
{
"include": ["src", "lingo.d.ts"]
}Execute a verificação de tipos habitual da aplicação. Uma declaração fora do projeto do compilador não impõe restrições a nenhuma chamada. Se a extração usar --types ou i18n.typesPath, inclua o caminho de saída efetivamente usado.
O que significa a interface gerada #
O arquivo estende LingoMessages com os textos de origem e suas opções. O exemplo a seguir ilustra a estrutura gerada:
export {};
declare module "@lingo.dev/react" {
interface LingoMessages {
"Hello, {name}.": {
values: { name: string | number };
context: "Greeting on the account dashboard";
};
"Save": {
context: "Submit settings" | "Bookmark an article";
};
}
}Gere esse arquivo novamente em vez de manter o exemplo à mão. A saudação agora exige values.name e o contexto extraído para ela. Save aceita qualquer um dos contextos registrados. Um texto de origem não listado não atende à restrição de MessageKey.
Sem entradas geradas, LingoMessages fica vazio e MessageKey permite qualquer string. Depois de preenchido, MessageKey passa a ser a união de suas chaves de string. O comportamento em tempo de execução não muda: essas restrições se aplicam a l.text e l.rich durante a edição.
Manter os tipos em dia com o texto de origem #
Execute a extração novamente após alterar textos, contextos ou marcadores. As mensagens removidas ficam órfãs e são excluídas da geração. Entradas sem contexto não geram uma assinatura, a menos que outra entrada ativa para o mesmo texto de origem forneça um contexto. Vários contextos para o mesmo texto de origem formam uma união.
Para verificar se os arquivos estão atualizados sem gravá-los:
npx lingo extract --src src --source-locale en --checkEssa verificação compara tanto o JSONC quanto as declarações com a extração atual. É uma verificação local, não uma solicitação de tradução. Execute-a junto com a verificação de tipos para evitar que uma declaração antiga defina, sem aviso, um inventário de mensagens desatualizado.
Tipos de valores e cobertura #
O gerador reconhece argumentos ICU de nível superior. Ele usa number para argumentos de plural, ordinal e número; string para argumentos de seleção; Date | number para argumentos de data/hora; e string | number para marcadores simples. Ele não identifica todos os marcadores aninhados em uma ramificação de plural, por isso teste explicitamente os valores dessas ramificações.
As restrições geradas para os textos de origem se aplicam a text e rich. As funções auxiliares plural e select mantêm suas próprias assinaturas de formas/opções. As chamadas com conteúdo formatado acrescentam um mapa opcional de tags, mas as declarações não verificam o posicionamento das tags no texto de destino.
Os tipos indicam se uma chamada corresponde ao contrato extraído do texto de origem. Os testes de renderização indicam se a tradução carregada consegue usar esses valores. Mantenha ambos: mesmo com uma chamada válida, a entrada pode estar ausente do catálogo ou a mensagem ICU de destino pode estar malformada.