Как извлечь и загрузить каталоги сообщений
Извлеките исходные сообщения, получите переведённый файл JSONC и соберите словарь для среды выполнения с метаданными соответствующей версии исходного файла.
Компонент содержит исходное сообщение и его контекст. При извлечении эти вызовы собираются в файл для перевода. При загрузке переведённые значения связываются с ключами компонента. В этом примере первое приветствие пройдёт все этапы работы с файлом, а в результате мы получим словарь Messages для провайдера.
Извлеките исходные сообщения #
Установите CLI и зависимости загрузчика в приложении:
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, инициализируйте именно этот файл и испанскую целевую локаль. Затем пройдите аутентификацию и привяжите движок локализации:
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 для изменения конфигурации: эта команда пересоздаёт записи файлов и может удалить расширенные параметры. Полная структура описана в разделе Конфигурация.
В новом проекте или после описанной подготовки существующего проекта запросите недостающие целевые файлы и дождитесь их получения. Пока команда ожидает завершения, не меняйте целевые файлы: при скачивании локальные изменения могут быть перезаписаны:
npx lingo push --backfill-missing --waitКогда запуск завершится, проверьте locales/es.jsonc. Прежде чем считать результат готовым, разберитесь со всеми отмеченными состояниями проверки и сбоями. При последующих изменениях исходного текста повторите извлечение и используйте npx lingo push --wait. Дозагрузка нужна для недостающих файлов, а не для обычного обновления существующего перевода.
Храните метаданные исходного файла вместе с соответствующей ревизией перевода #
Стандартный рабочий процесс перевода JSONC сохраняет в переводе метки @orphan исходного файла, но удаляет комментарии @context и @src. По одному лишь переводу загрузчик не может определить, какой странице принадлежало сообщение.
Сохраните извлечённый исходный файл той же ревизии, что и перевод. Выберите из него активные записи и сопоставьте их ключи с переведёнными значениями. Так вы исключите удалённые сообщения и сохраните возможность отбора по исходному маршруту. Ключи, которых нет в переводе, не добавляются, поэтому среда выполнения сможет использовать исходный текст как запасной вариант.
Разберите каталог в виде необработанного текста #
Создайте src/catalog.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 загрузите файлы как необработанный текст в модуле, который передаёт данные провайдеру:
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.