FAQ

Часто задаваемые вопросы и ответы о 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="Выберите животное">
      {/* Этот текст НЕ будет переведен */}
      <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="Выберите животное">
      {/* Этот текст БУДЕТ переведен */}
      <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 перед фиксацией изменений, чтобы поддерживать чистоту файлов переводов.

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

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

  1. Соберите локально, чтобы нормализовать ваши файлы lingo/:

    npm run build

  2. Проверьте ваш API-ключ, чтобы убедиться, что он настроен правильно:

    # Убедитесь, что в вашем файле .env содержится
GROQ_API_KEY=gsk_...

  3. Зафиксируйте обновлённые файлы:

    git add lingo/
git commit -m "Обновить переводы"

  4. Перезапустите сервер разработки после внесения изменений.

Могу ли я настроить собственный глоссарий?

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

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} />;

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

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