Extrair e carregar catálogos de mensagens

Extraia as mensagens de origem, obtenha um ficheiro JSONC traduzido e crie um mapa para utilização em tempo de execução com os metadados de origem correspondentes.

Um componente contém a mensagem de origem e o respetivo contexto. A extração reúne essas chamadas num ficheiro que pode ser traduzido. O carregamento associa os valores traduzidos às chaves do componente. Este guia acompanha a primeira saudação ao longo desse workflow baseado em ficheiros e gera o mapa Messages de que um fornecedor precisa.

Extrair as mensagens de origem #

Instale a CLI e as dependências do carregador na aplicação:

sh
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale en

A extração é executada localmente e não requer uma chave de API. Por predefinição, escreve locales/en.jsonc e lingo.d.ts. As opções explícitas --out e --types têm precedência sobre os valores configurados de i18n.messagesPath e i18n.typesPath, que, por sua vez, têm precedência sobre essas predefinições. Uma aplicação Pages com chamadas fora de src utiliza o diretório onde estas se encontram, como --src pages.

Examine a entrada da saudação. O valor é o modelo completo em inglês; a chave deriva da origem e do contexto. Os comentários que precedem a entrada registam @context para o significado, @src para a localização na origem e @orphan quando uma entrada extraída anteriormente já não está ativa. Reveja essas alterações antes de solicitar traduções.

Traduzir o catálogo selecionado #

Numa aplicação sem configuração do Lingo.dev, inicialize este ficheiro específico e o espanhol como idioma de destino. Em seguida, autentique-se e associe um motor de localização:

sh
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link

Precisa de acesso a um motor de localização ativado e de uma quota de consumo suficiente na conta. A secção Autenticação da CLI explica as credenciais para execuções não assistidas.

Se .lingo/config.json já existir, mantenha a respetiva associação e as restantes entradas de ficheiros. Adicione ou atualize a entrada que seleciona locales/en.jsonc e confirme que o idioma de origem do projeto é en. Se já existir uma base de referência, conclua as atualizações normais dos idiomas de destino existentes com npx lingo push --wait, resolva qualquer revisão pendente ou falha e examine as alterações obtidas antes de adicionar es a targetLocales. Mantenha a revisão de origem inalterada durante o preenchimento subsequente dos ficheiros em falta. A secção Adicionar um idioma explica esta sequência. Não utilize init --force para editar a configuração: este comando recria as entradas de ficheiros e pode eliminar opções avançadas. A secção Configuração descreve a estrutura completa.

No novo projeto, ou depois de concluir esta preparação num projeto existente, solicite os ficheiros de destino em falta e aguarde a sua obtenção. Não altere os ficheiros de destino enquanto o comando aguarda, pois a transferência pode substituir as edições locais:

sh
npx lingo push --backfill-missing --wait

Quando a execução terminar, examine locales/es.jsonc. Resolva qualquer estado de revisão ou falha comunicado antes de considerar o resultado concluído. Para alterações posteriores à origem, volte a executar a extração e utilize npx lingo push --wait; o preenchimento destina-se a ficheiros em falta, não a atualizações normais de um destino existente.

Manter os metadados de origem com a revisão de destino #

O workflow geral de tradução de JSONC mantém as marcações @orphan da origem no destino, mas elimina os comentários @context e @src. Um ficheiro de destino, por si só, não permite ao carregador determinar a que página pertencia uma mensagem.

Conserve o ficheiro de origem extraído da mesma revisão que o destino. Selecione as entradas ativas dessa origem e associe as respetivas chaves aos valores traduzidos do destino. Desta forma, exclui as mensagens removidas e mantém a possibilidade de selecionar por rota de origem. As chaves em falta no destino continuam ausentes, permitindo recorrer à origem em tempo de execução.

Analisar um catálogo em bruto #

Crie src/catalog.ts com este carregador definido na própria aplicação:

ts
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";

function readStringCatalog(raw: string) {
  const errors: ParseError[] = [];
  const value: unknown = parse(raw, errors, { allowTrailingComma: true });
  if (
    errors.length > 0 ||
    value === null ||
    typeof value !== "object" ||
    Array.isArray(value) ||
    Object.values(value).some((entry) => typeof entry !== "string")
  ) {
    throw new Error("Expected a flat JSONC object with string values");
  }
  return readLocaleFile(raw);
}

export function loadMatchedMessages(
  sourceJsonc: string,
  targetJsonc: string,
  include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
  const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
  const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
  return Object.fromEntries(
    active.filter(include).flatMap((entry) => {
      const value = target.get(entry.key);
      return value === undefined ? [] : [[entry.key, value]];
    }),
  );
}

readLocaleFile analisa a sintaxe e os metadados JSONC, mas não valida a estrutura em tempo de execução. Aceita matrizes e valores que não são cadeias de caracteres, apesar do tipo declarado para as entradas, e não devolve entradas quando a raiz é um valor primitivo ou nulo. A primeira função acima rejeita essas estruturas antes de os valores chegarem ao renderizador. Ambas as funções são locais e não efetuam operações de E/S.

Numa aplicação Vite, carregue os ficheiros como texto em bruto no módulo que disponibiliza o fornecedor:

ts
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";

export const spanishMessages = loadMatchedMessages(source, target);

Isto pressupõe que o módulo se encontra diretamente em src e que os tipos de cliente do Vite estão incluídos. Passe spanishMessages como messages com locale="es". A saudação deverá agora utilizar o modelo em espanhol obtido e continuar a substituir {name} por Ana. Verifique a redação e teste os casos em que faltam entradas: carregar um ficheiro e avaliar a sua qualidade linguística são tarefas distintas.

Selecionar apenas as entradas de origem necessárias para uma rota #

O predicado opcional include é aplicado às entradas de origem ativas antes da associação. Um carregador de página pode utilizar entry.metadata.src para incluir as suas próprias chamadas e os componentes partilhados. Faça essa seleção na origem, onde os metadados ainda existem. Mantenha a origem e o destino juntos ao colocar a aplicação em produção, para que a seleção por rota não utilize chaves de outra revisão.

O guia de Next Pages fornece um predicado de rota completo. O guia de TanStack utiliza este carregador para o catálogo de cada pedido. Os carregadores integrados de ambos podem filtrar ficheiros que contêm metadados, mas nenhum associa automaticamente os destinos sem comentários aos metadados de origem.

Referência dos auxiliares da especificação #

ExportaçãoContrato
readLocaleFile(content): LocaleFileAnalisar JSONC, incluindo vírgulas finais e comentários de bloco de metadados que precedem as entradas; os erros de sintaxe lançam exceções.
getActiveEntries(entries): LocaleEntry[]Manter as entradas em que metadata.orphan não é avaliado como verdadeiro.
LocaleFile{ entries: LocaleEntry[] }.
LocaleEntry{ key: string; value: string; metadata: EntryMetadata }.
EntryMetadatacontext, src e orphan opcionais.
computeKey(source, context?)Identidade normalizada de origem/contexto partilhada, também exportada pelo React.
buildIcuPlural(forms)Emitir as categorias cardinais conhecidas pela ordem canónica.
buildIcuSelect(forms)Emitir alternativas com as chaves ordenadas.

Os construtores ICU aceitam registos de cadeias de caracteres; os tipos plural e select do React acrescentam a forma obrigatória other. O catálogo resultante para utilização em tempo de execução é um mapa Messages simples, não um LocaleFile.

Os recursos existentes com chaves, os documentos e os módulos estáticos de idiomas em TypeScript utilizam os seus próprios processadores de formato, em vez deste guia de extração. Os projetos de exemplo mostram essas estruturas juntamente com aplicações React.