Быстрый старт

Основное преимущество Lingo.dev CLI — это эффективная локализация приложений и контента в формате markdown на целевые языки с помощью одной команды CLI.

Этот гид по быстрому старту предполагает, что вы либо собираетесь сделать своё приложение мультиязычным, либо уже настроили его для работы с 2+ языками. Поэтому руководство достаточно короткое, чтобы его можно было пройти менее чем за 10 минут, но при этом достаточно подробное, чтобы понять внутренние процессы.

После завершения этого руководства вы:

1. Локализуете контент приложения на испанский и японский языки с помощью AI-движка перевода;
2. Поймёте, как исходные файлы, целевые файлы и конфигурация работают вместе;
3. Настроите процесс локализации, который позволит масштабировать ваше приложение и контент в формате markdown на десятки языков и тысячи слов.

Начнём!

Предварительные требования

Markdown

Файлы в формате markdown — это структурированные документы, поэтому никакой предварительной настройки не требуется. Lingo.dev CLI обрабатывает файлы .md напрямую, сохраняя форматирование при локализации контента, так что вы можете перейти к Шагу 1.

Приложения

Чтобы сделать приложение мультиязычным, современные веб- и мобильные приложения требуют от разработчиков предварительной настройки конфигурации интернационализации (i18n).

Для этого быстрого старта мы создадим отдельный JSON-файл, чтобы продемонстрировать, как Lingo.dev CLI локализует контент приложения.

При интеграции с вашим реальным приложением следуйте нашим рекомендациям по фреймворкам:

• React: react-intl
• Vue: vue-i18n
• Svelte: svelte-i18n
• Angular: ngx-translate
• iOS: Localizable.xcstrings
• Android: strings.xml

Шаг 1. Инициализация проекта

Lingo.dev CLI использует стандартный конфигурационный файл i18n.json для указания настроек локализации. Чтобы создать его интерактивно, выполните команду:

bash npx lingo.dev@latest init

Она задаст вам вопросы о вашем проекте, а затем создаст файл `i18n.json` в корневой директории вашего проекта.

Файл будет выглядеть следующим образом:

```json
{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Давайте разберём каждый элемент конфигурации:

• locale.source — Язык, на котором ваша команда пишет. Эта настройка определяет, какие файлы содержат авторитетный контент. Вся локализация идёт от исходного языка к целевым.

• locale.targets — Массив кодов языков ISO 639-1, представляющих ваши целевые рынки. Каждый код соответствует отдельному файлу (или разделу внутри файла, в зависимости от формата). Вы можете начать с одного или двух языков и добавлять больше по мере расширения.

• buckets.json.include — Шаблоны, похожие на glob, которые указывают CLI, где искать и создавать файлы локалей. Специальный токен [locale] заменяется на каждый код языка. С шаблоном locales/[locale].json CLI ищет locales/en.json как исходный файл и генерирует locales/es.json и locales/ja.json как целевые. Вы можете указать несколько шаблонов и даже смешивать форматы в одной конфигурации.

Расширенные функции, которые вы откроете по мере роста вашего проекта:

• Несколько buckets для разных типов файлов или разделов вашего приложения
• Шаблоны exclude для пропуска определённых файлов
• lockedKeys для предотвращения перевода определённых значений

Создание исходного файла на английском языке

Для этого быстрого старта мы создадим файл локализации:

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

Эта команда создаёт директорию locales и исходный файл на английском языке с двумя ключами перевода. Ключи, такие как greeting, подходят для плоских структур, а ключи с пространством имён, такие как button.submit, помогают организовать более крупные приложения.

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

Шаг 2. Аутентификация

Lingo.dev CLI отправляет ваш контент в AI-движок перевода для локализации, поэтому сначала необходимо пройти аутентификацию.

Вариант 1. Прямой доступ к API LLM

Lingo.dev CLI помогает использовать модели LLM, такие как OpenAI или Anthropic, для локализации и перевода.

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

Для аутентификации создайте файл .env в корневой директории вашего проекта с вашим API-ключом:

# если вы используете OpenAI

OPENAI_API_KEY=sk-...

# если вы используете Anthropic

ANTHROPIC_API_KEY=sk-...

В качестве альтернативы, вместо использования .env, вы можете экспортировать переменную в текущей сессии shell:

export ANTHROPIC_API_KEY=sk-ant-...

Хотите добавить поддержку другого провайдера? Lingo.dev CLI — это проект с открытым исходным кодом, и мы приветствуем ваши вклады! Форкните репозиторий и отправьте pull request: github.com/lingodotdev/lingo.dev.

Вариант 2. Движок Lingo.dev

В качестве альтернативы вы можете создать бесплатный аккаунт в Lingo.dev Engine и использовать его в качестве AI-движка перевода.

Он предоставляет динамический выбор моделей, автоматическую маршрутизацию к различным моделям для каждой языковой пары, автоматические резервные модели, память переводов, которая учитывает прошлые переводы, и поддержку глоссария для терминологии, специфичной для вашего проекта. Доступны как бесплатные, так и платные варианты, и бесплатного тарифа Hobby будет достаточно для этого руководства.

Для аутентификации выполните команду:

npx lingo.dev@latest login

Важная деталь. Если вы используете браузер Brave или ваши расширения браузера блокируют процесс аутентификации, вы можете пройти аутентификацию вручную, добавив переменную окружения LINGODOTDEV_API_TOKEN в ваш файл .env:

LINGODOTDEV_API_TOKEN=...

Вы найдёте токен в настройках проекта Lingo.dev Engine.

Шаг 3. Настройка AI-движка перевода

Теперь, когда вы прошли аутентификацию, необходимо настроить, какой AI-движок перевода использовать.

Вариант 1. Прямой доступ к API LLM

Чтобы использовать OpenAI, обновите конфигурацию i18n.json, указав провайдера openai:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

Вы можете экспериментировать с различными подсказками, чтобы настроить поведение локализации, но мы обнаружили, что эта является хорошей отправной точкой!

Конфигурация provider управляет прямым доступом к LLM:

• id — Либо openai, либо anthropic
• model — Конкретная версия модели для использования. Примеры: gpt-4o-mini, gpt-4o (OpenAI) или claude-3-haiku, claude-3-sonnet (Anthropic).
• prompt — Системная подсказка, которая направляет поведение перевода. Заполнители {source} и {target} заменяются на фактические коды языков во время выполнения. Эта подсказка — ваша возможность задать терминологию, стиль и правила, специфичные для домена.

Вариант 2. Движок Lingo.dev

Если вы используете движок Lingo.dev в качестве AI-движка перевода, вы можете полностью пропустить узел provider.

Движок автоматически выбирает модели и подсказки на основе исследований команды Lingo.dev и настроек вашего движка.

Ваша конфигурация i18n.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Примечание: При использовании движка Lingo.dev полностью исключите узел provider. Движок автоматически выбирает модели и подсказки.

Шаг 4. Перевод

Чтобы локализовать ваше приложение, выполните команду:

npx lingo.dev@latest i18n

CLI создаст целевые файлы и обновит файл i18n.lock, который отслеживает отпечатки содержимого. Это гарантирует инкрементальные обновления при последующих запусках.

Теперь ваш контент приложения локализован!

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

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

Отсюда вы можете:

• Автоматизировать процесс: Интеграция CI/CD — Настройте интеграцию CI/CD, чтобы локализовать при каждом пуше и автоматически коммитить изменения обратно в ваш репозиторий через pull request или прямые коммиты;
• Понять внутренние механизмы: Как это работает — Узнайте об алгоритмах, оптимизации производительности и архитектурных решениях.