Extraia e carregue catálogos de mensagens

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

Um componente contém a mensagem de origem e seu contexto. A extração reúne essas chamadas em um arquivo que pode ser traduzido. O carregamento associa os valores traduzidos às chaves do componente. Esta receita acompanha a primeira saudação ao longo desse workflow de arquivos e gera o mapa Messages de que um provedor precisa.

Extraia a 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 exige chave de API. Por padrão, ela grava locales/en.jsonc e lingo.d.ts. As opções explícitas --out e --types têm precedência sobre os valores configurados em i18n.messagesPath e i18n.typesPath, que, por sua vez, têm precedência sobre os padrões. Uma aplicação Pages com chamadas fora de src usa o diretório em que elas estão, como --src pages.

Confira a entrada da saudação. O valor é o modelo completo em inglês; a chave é derivada da origem e do contexto. Os comentários que precedem a entrada registram @context para o significado, @src para a localização no código-fonte e @orphan quando uma entrada extraída anteriormente não está mais ativa. Revise essas alterações antes de solicitar traduções.

Traduza o catálogo selecionado #

Para uma aplicação sem configuração do Lingo.dev, inicialize exatamente este arquivo com espanhol como idioma de destino. Depois, autentique-se e vincule um engine de localização:

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

Você precisa de acesso a um engine de localização habilitado e de uma cota de consumo suficiente na conta. Autenticação da CLI explica as credenciais para execuções não supervisionadas.

Se .lingo/config.json já existir, preserve seu vínculo e as demais entradas de arquivo. Adicione ou atualize a entrada que seleciona locales/en.jsonc e confirme que o idioma de origem do projeto é en. Se já houver uma base estabelecida, conclua as atualizações normais dos idiomas de destino existentes com npx lingo push --wait, resolva qualquer pendência de revisão ou falha e confira as alterações recebidas antes de adicionar es a targetLocales. Mantenha a mesma revisão do código-fonte durante o preenchimento dos arquivos ausentes na etapa seguinte. Adicionar um idioma explica essa ordem. Não use init --force para editar a configuração: esse comando recria as entradas de arquivo e pode descartar opções avançadas. Configuração apresenta a estrutura completa.

Para o projeto novo, ou após concluir essa preparação do projeto existente, solicite os arquivos de destino ausentes e aguarde o recebimento. Não altere os arquivos de destino enquanto o comando estiver aguardando, pois o processo de download pode sobrescrever edições locais:

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

Quando a execução terminar, confira locales/es.jsonc. Resolva qualquer estado de revisão ou falha informado antes de considerar o resultado completo. Para alterações posteriores na origem, execute a extração novamente e use npx lingo push --wait; o preenchimento serve para arquivos ausentes, não para atualizações normais de um destino existente.

Mantenha os metadados de origem na mesma revisão do destino #

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

Mantenha o arquivo de origem extraído na mesma revisão do destino. Selecione as entradas ativas dessa origem e associe suas chaves aos valores traduzidos do destino. Isso exclui mensagens removidas e preserva a opção de selecionar por rota de origem. As chaves ausentes no destino continuam ausentes, permitindo que o ambiente de execução use a origem como alternativa.

Analise um catálogo bruto #

Crie src/catalog.ts com este carregador definido pela 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. Ele aceita arrays e valores que não são strings, apesar do tipo de entrada declarado, e não retorna entradas quando a raiz é um valor primitivo ou nulo. A primeira função acima rejeita essas estruturas antes que os valores cheguem ao renderizador. As duas funções são locais e não realizam E/S.

Em uma aplicação Vite, carregue os arquivos como texto bruto no módulo que fornece o provedor:

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);

Isso pressupõe que o módulo esteja diretamente em src e que os tipos de cliente do Vite estejam incluídos. Passe spanishMessages como messages com locale="es". A saudação agora deve usar o modelo em espanhol recebido e continuar substituindo {name} por Ana. Confira o texto e teste os casos de entradas ausentes; carregar um arquivo é diferente de avaliar sua qualidade linguística.

Selecione apenas as entradas de origem de que uma rota precisa #

O predicado opcional include é executado nas entradas de origem ativas antes da associação. Um carregador de página pode usar entry.metadata.src para incluir suas próprias chamadas e componentes compartilhados. Faça essa seleção na origem, onde os metadados ainda existem. Mantenha a origem e o destino juntos na implantação para que a seleção por rota não use chaves de outra revisão.

A receita do Next Pages fornece um predicado de rota completo. A receita do TanStack usa este carregador no catálogo da requisição. Os carregadores integrados dessas soluções podem filtrar arquivos com metadados, mas nenhum deles associa automaticamente destinos sem comentários aos metadados de origem.

Referência dos utilitários da especificação #

ExportaçãoContrato
readLocaleFile(content): LocaleFileAnalisa JSONC, incluindo vírgulas finais e os comentários de bloco com metadados que precedem as entradas; erros de sintaxe geram exceções.
getActiveEntries(entries): LocaleEntry[]Mantém 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 e compartilhada de origem/contexto, também exportada pelo React.
buildIcuPlural(forms)Emite as categorias cardinais conhecidas na ordem canônica.
buildIcuSelect(forms)Emite alternativas com chaves ordenadas.

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

Recursos existentes com chaves, documentos e módulos estáticos de idioma em TypeScript usam seus próprios processadores de formato, em vez desta receita de extração. Os projetos de exemplo mostram essas estruturas junto com aplicações React.