Как извлечь и загрузить каталоги сообщений

Извлеките исходные сообщения, получите переведённый файл JSONC и соберите словарь для среды выполнения с метаданными соответствующей версии исходного файла.

Компонент содержит исходное сообщение и его контекст. При извлечении эти вызовы собираются в файл для перевода. При загрузке переведённые значения связываются с ключами компонента. В этом примере первое приветствие пройдёт все этапы работы с файлом, а в результате мы получим словарь Messages для провайдера.

Извлеките исходные сообщения #

Установите CLI и зависимости загрузчика в приложении:

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

Извлечение выполняется локально и не требует ключа API. По умолчанию создаются файлы locales/en.jsonc и lingo.d.ts. Явно заданные флаги --out и --types переопределяют настройки i18n.messagesPath и i18n.typesPath, а те — значения по умолчанию. Если в приложении Pages есть вызовы за пределами src, укажите фактический каталог, например --src pages.

Проверьте запись приветствия. Её значение — полный английский шаблон, а ключ формируется из исходного текста и контекста. Комментарии перед записью содержат @context для пояснения смысла, @src для расположения в исходном коде и @orphan, если ранее извлечённая запись больше не активна. Проверьте эти изменения, прежде чем запрашивать переводы.

Переведите выбранный каталог #

Если в приложении нет конфигурации Lingo.dev, инициализируйте именно этот файл и испанскую целевую локаль. Затем пройдите аутентификацию и привяжите движок локализации:

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

Вам нужен доступ к включённому движку локализации и достаточный неиспользованный лимит в учётной записи. В разделе Аутентификация CLI описаны учётные данные для запусков без участия человека.

Если .lingo/config.json уже существует, сохраните его привязку и записи других файлов. Добавьте или обновите запись, которая выбирает locales/en.jsonc, и убедитесь, что исходная локаль проекта — en. Если базовые переводы уже есть, сначала завершите обычные обновления существующих целевых локалей с помощью npx lingo push --wait. Разберитесь со всеми запросами на проверку и сбоями, проверьте полученные изменения и только затем добавьте es в targetLocales. Во время последующей дозагрузки не меняйте ревизию исходного файла. Этот порядок описан в разделе Как добавить язык. Не используйте init --force для изменения конфигурации: эта команда пересоздаёт записи файлов и может удалить расширенные параметры. Полная структура описана в разделе Конфигурация.

В новом проекте или после описанной подготовки существующего проекта запросите недостающие целевые файлы и дождитесь их получения. Пока команда ожидает завершения, не меняйте целевые файлы: при скачивании локальные изменения могут быть перезаписаны:

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

Когда запуск завершится, проверьте locales/es.jsonc. Прежде чем считать результат готовым, разберитесь со всеми отмеченными состояниями проверки и сбоями. При последующих изменениях исходного текста повторите извлечение и используйте npx lingo push --wait. Дозагрузка нужна для недостающих файлов, а не для обычного обновления существующего перевода.

Храните метаданные исходного файла вместе с соответствующей ревизией перевода #

Стандартный рабочий процесс перевода JSONC сохраняет в переводе метки @orphan исходного файла, но удаляет комментарии @context и @src. По одному лишь переводу загрузчик не может определить, какой странице принадлежало сообщение.

Сохраните извлечённый исходный файл той же ревизии, что и перевод. Выберите из него активные записи и сопоставьте их ключи с переведёнными значениями. Так вы исключите удалённые сообщения и сохраните возможность отбора по исходному маршруту. Ключи, которых нет в переводе, не добавляются, поэтому среда выполнения сможет использовать исходный текст как запасной вариант.

Разберите каталог в виде необработанного текста #

Создайте src/catalog.ts со следующим загрузчиком, реализованным в приложении:

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 разбирает синтаксис JSONC и метаданные, но не проверяет структуру данных во время выполнения. Несмотря на объявленный тип записи, функция принимает массивы и нестроковые значения. Если в корне находится примитивное значение или null, она не возвращает записей. Первая функция выше отклоняет такие структуры до того, как значения попадут в рендерер. Обе функции локальны и не выполняют ввод-вывод.

В приложении Vite загрузите файлы как необработанный текст в модуле, который передаёт данные провайдеру:

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

Здесь предполагается, что модуль находится непосредственно в src и клиентские типы Vite подключены. Передайте spanishMessages как messages с помощью locale="es". Теперь приветствие должно использовать полученный испанский шаблон и по-прежнему заменять {name} на Ana. Проверьте сам текст и поведение при отсутствии записей: загрузка файла и оценка качества перевода — разные задачи.

Выберите только те исходные записи, которые нужны маршруту #

Необязательный предикат include применяется к активным исходным записям перед сопоставлением. Загрузчик страницы может использовать entry.metadata.src, чтобы включить вызовы самой страницы и общих компонентов. Выполняйте отбор по исходному файлу, где метаданные ещё сохранены. При развёртывании храните исходный файл и перевод вместе, чтобы при отборе по маршруту не использовались ключи из другой ревизии.

В примере для Next Pages приведён полный предикат маршрута. В примере для TanStack этот загрузчик используется для каталога запроса. Встроенные загрузчики обоих решений умеют фильтровать файлы с метаданными, но ни один из них не сопоставляет автоматически переводы без комментариев с метаданными исходного файла.

Справочник вспомогательных функций спецификации #

ЭкспортКонтракт
readLocaleFile(content): LocaleFileРазбирает JSONC, включая завершающие запятые и предшествующие блочные комментарии с метаданными. При синтаксической ошибке выбрасывает исключение.
getActiveEntries(entries): LocaleEntry[]Оставляет записи, у которых metadata.orphan не приводится к true.
LocaleFile{ entries: LocaleEntry[] }.
LocaleEntry{ key: string; value: string; metadata: EntryMetadata }.
EntryMetadataНеобязательные context, src и orphan.
computeKey(source, context?)Общий нормализованный идентификатор исходного текста и контекста, который также экспортируется из React.
buildIcuPlural(forms)Выводит известные категории количественных числительных в каноническом порядке.
buildIcuSelect(forms)Выводит варианты с отсортированными ключами.

Функции построения ICU принимают записи со строковыми значениями. Типы React для plural и select добавляют обязательную форму other. Полученный каталог для среды выполнения — обычный словарь Messages, а не LocaleFile.

Для существующих ресурсов с ключами, документов и статических модулей локалей TypeScript используются отдельные обработчики форматов, а не описанный здесь способ извлечения. В примерах проектов такие структуры показаны наряду с приложениями React.