Часто задаваемые вопросы

Часто задаваемые вопросы и ответы о Lingo.dev Compiler.

Могу ли я переводить строковые литералы?

Lingo.dev Compiler следует соглашению, что всё в JSX подлежит локализации. Строковые литералы вне компонентов JSX по замыслу не локализуются.

Текущее поведение:

// Это НЕ будет переведено
const message = "Hello world";
const errorText = "Something went wrong";

// Это БУДЕТ переведено
function Component() {
  return <h1>Hello world</h1>;
}

Как сделать литералы локализуемыми:

Вы можете сделать строковые литералы локализуемыми, обернув их в фрагменты JSX:

// До: Не локализуемо
const message = "Hello world";

// После: Локализуемо с использованием фрагментов
const message = <>Hello world</>;

// Использование в вашем компоненте
function Component() {
  return <div>{message}</div>;
}

Альтернативный подход:

// Для динамических сообщений
function getLocalizedMessage() {
  return <>Something went wrong</>;
}

// Для условного текста
const statusText = isError ? <>Error occurred</> : <>Success</>;

Это соглашение обеспечивает последовательное поведение локализации, сохраняя чёткие границы между локализуемым и нелокализуемым контентом.

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

Почему мои компоненты на основе коллекций не переводятся?

В настоящее время компилятор имеет ограничение для компонентов, основанных на Adobe React-Aria/React-Stately, которые ожидают коллекции в качестве дочерних элементов. Прямой текст в элементах коллекции не локализуется автоматически.

Это затрагивает такие компоненты, как Select, Listbox, Menu и аналогичные компоненты на основе коллекций из библиотек, таких как HeroUI, NextUI и другие реализации React-Aria.

Текущее поведение:

import { Select, SelectItem } from "@heroui/react";

export default function SelectExample() {
  return (
    <Select label="Select an animal">
      {/* Этот текст НЕ будет переведён */}
      <SelectItem key="cat" textValue="Cat">
        Cat
      </SelectItem>
      <SelectItem key="dog" textValue="Dog">
        Dog
      </SelectItem>
    </Select>
  );
}

Обходное решение:

Оберните текст в фрагменты JSX, чтобы сделать его локализуемым:

import { Select, SelectItem } from "@heroui/react";

export default function SelectWithWorkaround() {
  return (
    <Select label="Select an animal">
      {/* Этот текст БУДЕТ переведён */}
      <SelectItem key="cat" textValue="Cat">
        <>Cat</>
      </SelectItem>
      <SelectItem key="dog" textValue="Dog">
        <>Dog</>
      </SelectItem>
    </Select>
  );
}

Это ограничение затрагивает любые компоненты, использующие паттерн коллекций React-Aria, где текст передаётся напрямую как дочерние элементы коллекции. Мы работаем над улучшением поддержки компилятора для таких случаев.

Какие фреймворки поддерживаются?

Компилятор Lingo.dev в настоящее время поддерживает следующие фреймворки React:

Next.js (только App Router)
React Router v6+
Remix (последняя версия)
Vite + React

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

Могу ли я добавить больше языков?

Да! Вы можете расширить поддержку языков, настроив пользовательские модели прямо в конфигурации компилятора:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de", "pt", "it"],
  models: {
    "*:pt": "qwen/qwen3-32b",
    "en:it": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "qwen/qwen3-32b",
  },
};

lingoCompiler.next(compilerConfig)(nextConfig);

См. расширенную конфигурацию для подробностей.

Могу ли я использовать пользовательские подсказки?

Да! Вы можете настроить подсказки для перевода прямо в конфигурации компилятора:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "Вы профессиональный переводчик, специализирующийся на технической документации. Переводите с {SOURCE_LOCALE} на {TARGET_LOCALE}, сохраняя техническую точность.",
};

Для пользовательских глоссариев включите определения терминов в вашу подсказку. Ознакомьтесь с подсказкой по умолчанию для лучших практик.

Могу ли я использовать больше провайдеров LLM?

В настоящее время компилятор Lingo.dev интегрируется с Lingo.dev Engine и несколькими другими провайдерами LLM.

Мы хотели бы поддерживать больше провайдеров LLM в будущем — свяжитесь с нами или отправьте нам pull request!

Нужен ли мне ключ API GROQ в CI/CD?

Обычно нет. Если вы собираете приложение локально, все переводы будут сохранены в директории lingo/. Вашему CI/CD не нужно будет вызывать LLM для перевода строк.

В качестве альтернативы вы можете добавить переменную GROQ_API_KEY в ваш CI/CD и выполнять все переводы там во время сборки, но мы не рекомендуем этот подход, чтобы сохранить больший контроль над финальными переводами.

Могу ли я редактировать переводы?

Да! Вы можете вручную редактировать файл lingo/dictionary.js. Он экспортирует объект с переводами для всех файлов и записей. Вы можете редактировать текст для каждого языка в свойстве content. Ваши изменения будут сохранены до тех пор, пока исходный текст в React-компонентах не будет обновлен.

Не любите редактировать JavaScript-объекты? Мы скоро выпустим редактор, чтобы улучшить процесс редактирования. Дайте нам знать, если вам это интересно!

Как я могу перевести заново всё приложение, конкретный файл или язык?

Чтобы перевести заново всё приложение, удалите файл dictionary.js из директории lingo/.

Чтобы перевести заново только определённые файлы, вы можете удалить их ключ (имя файла) из dictionary.js.

Если вы хотите перевести заново определённый язык, вам нужно удалить все записи для этого языка.

Зачем мне нужно собирать приложение локально?

Локальная сборка нормализует ваши файлы перевода в директории lingo/ за счёт:

Удаления неиспользуемых ключей перевода
Обновления отпечатков содержимого
Обеспечения согласованного форматирования файлов
Оптимизации для развёртывания в продакшене

Всегда запускайте npm run build перед фиксацией изменений, чтобы поддерживать чистоту файлов перевода.

Переводы отсутствуют!

Если переводы отсутствуют:

Соберите локально, чтобы нормализовать ваши файлы в директории lingo/:
```
npm run build
```
Проверьте ваш API-ключ, чтобы убедиться, что он правильно настроен:
```
# Убедитесь, что ваш .env файл содержит
GROQ_API_KEY=gsk_...
```
Зафиксируйте обновлённые файлы:
```
git add lingo/
git commit -m "Update translations"
```
Перезапустите ваш сервер разработки после внесения изменений.

Могу ли я настроить пользовательский глоссарий?

Да! Используйте пользовательские подсказки, чтобы определить терминологию и глоссарии прямо в конфигурации вашего компилятора:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "Вы профессиональный переводчик. Используйте эти термины последовательно: 'Dashboard' должно быть 'Tableau de bord' на французском, 'Settings' должно быть 'Configuración' на испанском. Переведите с {SOURCE_LOCALE} на {TARGET_LOCALE}.",
};

Как компилятор обрабатывает множественные числа?

Компилятор автоматически обрабатывает базовые шаблоны множественного числа, но для сложных правил множественного числа вам может понадобиться соответствующим образом структурировать ваш JSX:

// Компилятор обработает это корректно
<p>{count === 1 ? <>1 элемент</> : <>{count} элементов</>}</p>

Как насчёт производительности в продакшене?

Компилятор Lingo.dev оптимизирован для продакшена:

Нулевая стоимость в рантайме — переводы предварительно компилируются
Разделение бандлов — загружается только активная локаль
Tree shaking — неиспользуемые переводы удаляются
Дружественность к CDN — статические файлы переводов эффективно кэшируются

Могу ли я использовать это с TypeScript?

Да! Компилятор работает без проблем с проектами на TypeScript. Все предоставленные React-компоненты полностью типизированы:

import { LocaleSwitcher } from "lingo.dev/react/client";

// Полная поддержка TypeScript
const locales: string[] = ["en", "es", "fr"];
<LocaleSwitcher locales={locales} />;

Как сообщить об ошибках или запросить новые функции?

GitHub Issues: Создать задачу
Сообщество в Discord: Присоединиться к нашему Discord
Запросы функций: Используйте обсуждения на GitHub для предложений функций

Следующие шаги

Начать работу: Руководство по быстрому старту
Интеграция с фреймворками: Next.js, React Router, Vite
Расширенные функции: Опции конфигурации