Альфа
Lingo.dev Compiler находится на стадии альфы. Он нестабилен, не рекомендуется для использования в production, а API могут меняться от релиза к релизу.
Lingo.dev Compiler создает и поддерживает директорию .lingo/ в корне проекта, где хранятся метаданные переводов и кэш. Понимание структуры этой директории поможет вам управлять переводами в системе контроля версий, разбираться с отсутствующими переводами и оптимизировать скорость сборки.
Директория .lingo/#
Compiler автоматически создает эту директорию при первой сборке. В ней хранятся все метаданные переводов, которые использует пайплайн сборки:
.lingo/
metadata.json # Translation cache and content hashes
locale-resolver.server.ts # Optional: custom server-side locale resolver
locale-resolver.client.ts # Optional: custom client-side locale resolvermetadata.json#
Это основной файл в директории .lingo/. В нем хранятся:
- Хеши содержимого — стабильные идентификаторы на основе хеша для каждой переводимой строки
- Кэшированные переводы — сгенерированные переводы для каждой пары локалей
- Снимки исходного текста — исходный текст на момент перевода, который используется для отслеживания изменений
Compiler читает этот файл в начале каждой сборки. Для строк с совпадающими хешами повторно используются кэшированные переводы. Строки с изменившимися или отсутствующими хешами отправляются в настроенный провайдер перевода.
Коммитьте в систему контроля версий
Всегда коммитьте .lingo/metadata.json в репозиторий. Production-сборки в режиме cache-only берут переводы только из этого файла. Если он не закоммичен, production-сборка завершится ошибкой.
Что важно учесть в .gitignore#
Не добавляйте .lingo/ в .gitignore. Эта директория должна отслеживаться в системе контроля версий. Вот типичный .gitignore для проекта, использующего Compiler:
# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.envsourceRoot#
Опция sourceRoot определяет, какую директорию Compiler сканирует в поиске переводимых React-компонентов:
{
sourceRoot: "./app", // Next.js App Router
// or
sourceRoot: "src", // Vite + React
}Compiler рекурсивно сканирует все файлы .tsx, .ts, .jsx и .js внутри sourceRoot в поисках переводимого JSX-контента. Файлы за пределами этой директории не обрабатываются.
| Значение sourceRoot | Что сканируется |
|---|---|
"./app" | Все файлы в директории app/ (соглашение Next.js) |
"src" | Все файлы в директории src/ (соглашение Vite) |
"." | Все файлы в корне проекта (удобно для монорепозиториев с общими пакетами) |
Чем шире sourceRoot, тем больше файлов сканируется, а значит, тем дольше идет сборка. Старайтесь делать его как можно уже. Если перевод нужен только для части файлов, используйте вместо этого опцию useDirective.
Режим явного включения с 'use i18n'#
По умолчанию Compiler переводит весь JSX-текст в sourceRoot. Чтобы переключиться в режим явного включения, задайте useDirective: true:
{
useDirective: true,
}В режиме явного включения обрабатываются только файлы, которые начинаются с директивы 'use i18n':
'use i18n';
export function Welcome() {
return <h1>Welcome to our app</h1>;
// This text IS translated
}Файлы без этой директивы пропускаются:
export function InternalAdmin() {
return <h1>Admin Dashboard</h1>;
// This text is NOT translated
}Когда использовать режим явного включения#
| Сценарий | Рекомендуемый режим |
|---|---|
| Небольшое приложение, где нужно переводить весь контент | По умолчанию (useDirective: false) |
| Большая кодовая база, где перевод нужен только для части пользовательских страниц | Явное включение (useDirective: true) |
| Монорепозиторий с общими внутренними и внешними компонентами | Явное включение (useDirective: true) |
| Постепенное внедрение — добавление i18n в существующее приложение | Явное включение (useDirective: true) |
lingoDir#
Опция lingoDir меняет расположение директории с метаданными:
{
lingoDir: ".lingo", // Default
// or
lingoDir: ".translations", // Custom location
}Это удобно, если .lingo/ конфликтует с уже существующей директорией в вашем проекте.
