Verificar os tipos das chamadas de mensagens

Gere e inclua declarações que verificam as cadeias de texto de origem, os contextos e os valores das mensagens durante a edição.

Uma chamada de mensagem pode ser válida em TypeScript e, ainda assim, pedir a entrada errada do catálogo. Um contexto alterado ou um marcador de posição mal escrito pode deixar o texto de origem ou {name} no ecrã. A extração gera declarações que integram as mensagens de origem conhecidas no sistema de tipos da aplicação.

Gerar e incluir a declaração #

Com a CLI instalada, execute:

sh
npx lingo extract --src src --source-locale en

Os ficheiros de saída predefinidos 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 o inclua. Mantenha as restantes entradas:

json
{
  "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 utilizar --types ou i18n.typesPath, inclua esse caminho de saída em vez do predefinido.

O que significa a interface gerada #

O ficheiro estende LingoMessages com cadeias de texto de origem e as respetivas opções. Este exemplo ilustra a estrutura gerada:

ts
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";
    };
  }
}

Volte a gerar este ficheiro em vez de atualizar o exemplo manualmente. A saudação passa a exigir values.name e o respetivo contexto extraído. Save aceita qualquer um dos contextos registados. Uma cadeia de texto de origem que não conste da lista não satisfaz a restrição de MessageKey.

Sem entradas geradas, LingoMessages está vazio e MessageKey permite qualquer cadeia de texto. Depois de preenchido, MessageKey passa a ser a união das suas chaves do tipo cadeia de texto. O comportamento em tempo de execução mantém-se: estas restrições aplicam-se a l.text e l.rich durante a edição.

Manter os tipos em dia com o texto de origem #

Repita a extração depois de alterar o texto, o contexto ou os marcadores de posição. As mensagens removidas ficam órfãs e são excluídas da geração. As entradas sem contexto não dão origem a nenhuma assinatura gerada, a menos que outra entrada ativa para a mesma cadeia de texto de origem forneça contexto. Vários contextos para a mesma cadeia de texto de origem formam uma união.

Para verificar se os ficheiros estão atualizados sem os gravar:

sh
npx lingo extract --src src --source-locale en --check

Esta operação compara tanto o JSONC como as declarações com a extração atual. É uma verificação local, não um pedido de tradução. Execute-a juntamente com a verificação de tipos para evitar que uma declaração desatualizada continue a definir, sem aviso, o inventário de mensagens do dia anterior.

Tipos de valores e cobertura #

O gerador reconhece argumentos ICU de nível superior. Utiliza 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 de posição simples. Não deteta todos os marcadores de posição aninhados num ramo de plural, pelo que deve testar explicitamente os valores desses ramos.

As restrições geradas para as cadeias de texto de origem aplicam-se a text e rich. As funções auxiliares plural e select mantêm as suas próprias assinaturas de formas/opções. As chamadas com formatação avançada acrescentam um mapa opcional de etiquetas, mas as declarações não verificam o posicionamento das etiquetas na tradução de destino.

Os tipos indicam se uma chamada respeita o contrato extraído do texto de origem. Os testes de renderização indicam se a tradução carregada consegue utilizar esses valores. Mantenha ambos: mesmo uma chamada válida pode deparar-se com uma entrada em falta no catálogo ou com ICU malformado na tradução de destino.